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, which the canvas enforces as you draw: 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 routing connector takes incoming connections only, and its targets come from Target Pipelines and Default Pipelines in its form, which warns with No routes configured while the route table is empty.
• 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.
• Component 'name' (section) is not available in the ClickStack distribution. means the configuration is locked to ClickStack, available in private preview, and uses a component ClickStack does not ship. Remove the component, or create a new configuration on OpenTelemetry Collector Contrib and paste the YAML into it. The distribution of an existing configuration cannot be changed. See Collector distributions.
• The AI assistant reports Collector version 2.36.0 is not supported. on a ClickStack configuration. The assistant validates against OpenTelemetry Collector Contrib only; use the editor's own validation for ClickStack configurations. See AI assistant.
• A routing connector target shown as (not found) names a pipeline that was renamed or deleted. Pick the pipeline again under Target Pipelines or Default Pipelines. See Route with the routing connector.

Validation is unavailable

• The status row shows validation unavailable · config not checked when the editor cannot reach the validation service, with the reason beneath it. The configuration has not been judged invalid; it has not been checked. You can keep editing, and applying YAML is allowed with the Apply tooltip Validation unavailable — applying unchecked YAML. Retry after a moment; the check runs again on your next change. See Validation status.
• The CLI reports the same outage as could not validate with exit code 1, and telflo config push saves nothing. The API answers such requests with 503. See CLI.
• The AI assistant skips its validation step during an outage rather than treating the configuration as broken. See AI assistant.

A component is missing from the palette

The palette offers the components the configuration's collector distribution ships. A ClickStack configuration, available in private preview, hides the rest. To use a component ClickStack does not include, create a new configuration on OpenTelemetry Collector Contrib. If ClickStack is not enabled for your account, every configuration is created on OpenTelemetry Collector Contrib and shows the full palette. See Collector distributions.

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, and its collector log opens with The test was never executed: followed by the reason the testing service gave, for example that the requested collector version is not installed on the test runner. A run started through the API or telflo test carries the same text in the run's stderr; telflo test prints it after test run errored: and exits with code 1.
• 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.
• A configuration that reads ${env:NAME} variables fails to apply when a variable is missing on the host. The install dialog lists the variables under Configuration environment variables (optional); a variable you left unchecked must be exported on the host, or delivered to the pods on a Kubernetes supervisor fleet, before the collector starts. See Install collectors.
• 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.

A ClickStack configuration does not install on a server fleet

The Linux bundle and Quick Deploy installs for a server fleet download OpenTelemetry Collector Contrib binaries. When the deploy group's configuration targets ClickStack, available in private preview, those installs fail with Collector v2.36.0 does not ship binaries for platform .... The Container image (GHCR) option in the same dialog runs Telflo's ClickStack collector image instead, and a Kubernetes supervisor fleet deploys the configuration with the ClickHouse connection details. See ClickStack configurations.

A container collector collects nothing from host files

• A collector installed with the Container image (GHCR) — pull and run platform sees only the paths mounted into its container. A filelog receiver pointed at an unmounted directory reads an empty directory, and a file_storage extension without a writable mount loses its checkpoints on restart. Declare the paths as volume mounts on the deploy group and reveal the run command again; the install dialog warns with This config reads paths the container won't see while a path is uncovered.
• A mount whose host or mount path is not absolute, contains a .. segment, or contains spaces or characters other than letters, digits, ., _, -, and / is left out of the run command without an error. The deploy group dialog flags an empty or relative path under the mount. Rename the path, or mount its parent directory.

The API or CLI rejects the ClickStack distribution

Unknown collector distribution: 'clickstack' (422) is returned when a request names clickstack on POST /configurations, POST /validate, or POST /testing/runs, when telflo test is run with --distribution clickstack, or when telflo validate --distribution clickstack is run with a credential; without one, telflo validate falls back to the anonymous validator, which accepts ClickStack. The API currently offers only otelcol-contrib. Omit the distribution to use the default. telflo test --config <id> on a configuration locked to ClickStack, available in private preview, still runs on that configuration's pin, because the API inherits the stored version's distribution; telflo validate --config <id> and telflo test -f <file> --config <id> name the pin explicitly and are refused for such a configuration. See API endpoints and CLI.

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: check that Enable AI Features is on in Settings > AI, then open the assistant with the AI button in the editor toolbar. If the panel shows Request AI, your membership in the current organization needs access; request it there. 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.

telflo login does not complete

• The browser page shows Paste this code into your terminal instead of finishing. Some browsers, notably Safari and Brave, block the hand-off to the CLI. Copy the Login code and paste it into the terminal that is still running telflo login, then press Enter. The code works once and expires shortly; if the terminal has already given up, run telflo login again and use the new code. See CLI.
• Timed out waiting for the browser — run 'telflo login' again, or use --token. means no approval reached the CLI within five minutes. On a machine without a browser, such as an SSH session, run telflo login --no-browser, open the printed URL where you are signed in to Telflo, and paste the code it shows; telflo login --code <code> finishes a login with a code you already copied.
• Login was denied in the browser. means Cancel was selected on the Authorize Telflo CLI page. Run telflo login again.
• That doesn't look like a Telflo login code. means the pasted value was incomplete. Copy the whole code shown on the login page, or a token starting with tf_.
• No organizations found means your account is not a member of any organization. Join or create one in Telflo first, then run telflo login again.
• Invalid CLI login request means the page was opened without the parameters telflo login adds to its URL. Run telflo login again rather than reopening a saved URL.
• In the Use a CI token form, No service accounts exist in this organization. means an admin must first create one under Settings > Service Accounts and then run telflo login again, and You're not an admin of the selected organization means you cannot mint a token there: pick an organization you administer, or go Back and select Continue as to sign in as yourself.
• The login exits with code 3 on these failures, except a pasted value that fails the code check, which is a usage error and exits with code 2. telflo login --token tf_... with a token from a service account bypasses the browser entirely.

An MCP client cannot connect, or its tool calls fail

Errors from the MCP server, such as a 401 when a client connects, an Authorize page that stops with an error, Pass org_id — this account belongs to several organizations, or a pipeline test that returns status: "Running", are listed with their fixes in MCP server troubleshooting. Ask the agent to call whoami first: it reports who the calls act as and in which organization.

An API token is rejected

• A deleted or expired token no longer authenticates. Token values cannot be retrieved after creation; open the token's service account under Settings > Service Accounts and create a new token. See Service accounts.
• A token stops authenticating when its service account is deleted, and when the service-account member, the @telflo.invalid address in the Permissions area, is removed from the organization. Restore the member, or create a replacement token on another service account.
• The CLI exits with code 3 on an authentication error, reporting Not logged in. Run 'telflo login', or set TELFLO_API_TOKEN. when it has no credential at all, or the API's message followed by check your token (or run 'telflo login'). Run telflo login again for a browser session, or check that TELFLO_API_TOKEN holds a current token with the access the command needs; a token set by --token or in the environment takes precedence over a stored session. See CLI.
• A session request refused with You are not an active member of this organization names an organization you have left or were removed from. Run telflo login again and choose a current organization.
• A read-only token is refused with This endpoint requires the 'write' claim on endpoints that create or change resources. Create a token with Allow write access. See API endpoints.
• Requests over the limit of 60 per minute for a credential are rejected with 429 and a Retry-After header. Retry after that pause; telflo test waits and retries on its own while polling a run, and slows its polling after the first ten polls.