Troubleshooting

A configuration does not validate

• The editor's validation status row shows the number of errors when the configuration does not pass. Expand it to see each issue with the affected component and a description. During manual YAML editing, the canvas shows Errors must be corrected. instead. See Validation.
• Check the connection rules: processors need incoming and outgoing connections, receivers need an outgoing connection, exporters need an incoming connection, connectors join two pipelines, and extensions have no connections.
• A schema error on a field means the value is not valid for the selected collector version. Correct the value, or change the collector version in the toolbar.

YAML edits do not appear on the canvas

Editing the YAML enters manual edit mode. The canvas updates when you select Apply, which is available once the edited YAML is valid. If the YAML cannot be parsed, fix the error reported in the YAML view, or select Undo All to discard the edits. See YAML editor.

Changes are missing

• Undo and redo are session-only and clear when you close the editor. Use Save to record a version.
• If you edited a read-only version, Telflo prompts you to save the changes as a new version. Confirm that you did.

A test run is stuck or failed

• A run that cannot start, because the testing service is unavailable, rate-limited, or offline, is marked Error.
• Confirm that a saved version is loaded.
• For pipelines with longer windows, such as batch or tail_sampling, increase the run duration so output has time to appear. See Running tests.
• If you are warned about a fixture mismatch, the sample file's shape does not match the selected signal type. Select a matching pipeline or file.

A collector does not pick up its configuration

• Pending pickup or Applying usually resolves on the next heartbeat.
• Apply failed means the collector rejected the configuration. Validate and test it, check the collector logs, then publish a corrected version and assign it to the instance's deploy group. See Update the configuration.
• Stale means no heartbeat for more than 15 minutes. Check the host and the collector process. The instance catches up when it reconnects.
• A collector pinned to a configuration ignores changes to its deploy group's configuration. Open Edit collector from the collector's Actions column and check for a pin; picking the option marked group default clears it.
• A newly installed collector that connects but processes no telemetry may still be running its bundled starter configuration because the fleet has no valid fleet token, for example after a revoke. Rotate to issue a new fleet token. Collectors that were already running keep their last applied configuration after a revoke. See Tokens & security.

A new collector does not appear

• Confirm that you installed with the run command or bundle for this fleet, so the collector has the correct endpoint. For a downloaded bundle, confirm that the OPAMP_TOKEN environment variable was set before the start script ran; the run command and Quick Deploy command carry the token themselves.
• A new collector usually appears within a minute. If it does not, check the host's network access to Telflo and the supervisor logs.
• A collector installed with a run command generated for a different fleet, or for a deploy group that no longer exists, is rejected before it appears in the fleet. The rejection is reported in the collector's logs; reinstall with a command generated from the intended group.
• On a Kubernetes fleet, collectors appear once the bridge connects and reports them. Confirm the bridge installed, and that the collector's namespace was onboarded. See Kubernetes fleets.

Duplicate collectors after a container restart

A collector run from the container image keeps its identity in a named volume. If the container runs without the volume, every time it is re-created it enrolls as a new collector and the old entry goes stale. Re-run the revealed command from the deploy dialog, which includes the volume, and delete the duplicate instances.

A Kubernetes fleet shows Unknown

Unknown means the bridge has stopped checking in, so Telflo has lost visibility; the collectors themselves may still be running. Check the bridge pod in the telflo-system namespace. A collector shown as Stale is the opposite case: the bridge is reporting, and that collector is gone from the cluster.

The AI assistant or Testing tab is missing

• AI assistant: enable AI in Settings > AI, then open it with the AI button in the editor toolbar, and request access if prompted. See AI access.
• Testing tab: it appears when testing is enabled for your account.

You cannot manage members or the organization

Member and organization management requires the Admin role. Contributors can build configurations but cannot manage the organization. See Members & roles.

An API token is rejected

• A deleted or expired token no longer authenticates. Token values cannot be retrieved after creation; create a new token in Settings > API Tokens. See API tokens.
• A token stops authenticating when its service-account member, the @telflo.invalid address in the Permissions area, is removed from the organization. Restore the member, or create a replacement token.
• Requests over the per-token rate limit are rejected. Retry after a pause.