Troubleshooting

Problems with the MCP server show up as an HTTP error when your client connects, on the Authorize page, or as a tool result with isError set. Findings such as valid: false or a test that ends Fail are normal results; see Results and errors.

When every tool call fails, ask the agent to call whoami; if that fails too, start with the first two sections.

Connecting and signing in

A credential the server cannot accept gets HTTP 401 before any tool runs, with the reason in the WWW-Authenticate header's error_description.

401 with Missing Authorization header

WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.telflo.com/.well-known/oauth-protected-resource/mcp"

For a client that signs you in, this is the normal start: it follows resource_metadata and opens the Authorize page. If no browser opens, start the sign-in from the client; in Claude Code, run /mcp, select telflo, and choose Authenticate. A client that cannot sign in needs a service-account token sent as Authorization: Bearer tf_...; under any other header name, it counts as no credential.

malformed tf_ token or expected a tf_ service-account token or a user access token

The first means the value after tf_ has a character other than letters, digits, _, and -, such as a copied quotation mark, or is still the tf_... placeholder. The second means the value is neither a tf_ token nor a sign-in token: it may be quoted, lack the tf_ prefix, belong to another service, or be an environment-variable reference the client sent as literal text. Paste the token exactly as the Copy your token dialog showed it, or add a new token.

token expired or invalid token

These apply when you sign in as yourself. Clients renew an expired token on their own; if one keeps reporting token expired, reconnect the server. Signing out of Telflo in your browser also makes every client sign in again (Revoke access).

invalid token means Telflo's sign-in did not issue the token, or it was altered; reconnect. It also appears when the server cannot check sign-ins, so if a fresh sign-in is refused too, retry in a few minutes or use a service-account token.

Every tool call fails with Telflo rejected the token (401)

On connect, the server checks only a tf_ token's format, so a deleted or expired token, or one whose service account was deleted or removed from the organization, still lists the tools; Telflo's API then refuses every call. Add a new token, on a new service account if that one is gone, replace the value, and reconnect. Signed in as yourself, reconnect.

The Authorize page shows an error

For what to check before Allow, see Connect a client.

Organizations and permissions

A service-account token acts in its own organization. Signed in as yourself, see Choose an organization for which one a call acts in; whoami shows it. Until you accept a team's invitation in Telflo, calls act in your personal workspace.

Not allowed (403)

The text after Not allowed (403): is the API's reason; the closing hint about read-only tokens and membership comes with every 403.

Telflo API error 404: Configuration not found

The id is not in the organization the call acts in, or the credential cannot see it. A never-published configuration is visible only to its creator, so a service-account token cannot see yours; connect as yourself, or publish first. Fleet not found, Deployment not found, and Test run not found mean the same for those inputs; Version not found means the configuration has no version with that number.

Validation and lint

Unknown collector distribution, could not validate, and could not lint say nothing about the YAML.

push_configuration returns status: "invalid"

The YAML failed validation on the configuration's collector, and nothing was saved. Fix each entry in errors, starting from its component_path. A description over 200 characters also returns status: "invalid", with a single validation failed error, even when the YAML is valid.

validate_configuration or lint_ottl returns valid: false

In lint_ottl results, note fields and skipped are not failures. A single-escaped regex class such as "\d" is reported because it matches nothing; write "\\d" or [0-9].

Validation passes, then the push returns invalid

Without configuration_id, validate_configuration checks on the server's default collector, while a push validates on the configuration's own pin. Pass configuration_id whenever the YAML belongs to a stored configuration. See Which collector runs it.

A configuration started from a flow does not validate

create_configuration cannot pin a collector, so the new configuration runs on the server default, which can differ from the flow's version. Set the collector version in the editor, or create the configuration with Use this flow in the app. See Start from a flow.

Unknown collector distribution

The API accepts only otelcol-contrib as a named distribution. A configuration locked to another distribution in the app, such as ClickStack, gets this error from validate_configuration, or run_pipeline_test with yaml, when you pass its configuration_id, as does a push once its latest version is published (status: "invalid"), which no YAML edit clears. To test such a configuration, pass configuration_id and no yaml. See Which collector runs it.

could not validate or could not lint

The validator or OTTL linter was unavailable, so nothing was checked or saved. Retry after a moment without changing the YAML. Telflo API error 502: HTTP 502 {"error":"Telflo API service unavailable"} and ... Fleet service unavailable are the same kind of outage.

Usage errors and refusals

A refused call changes nothing. Messages say deployment where these docs say deploy group.

An input is refused before the call reaches Telflo

Every id input must be a UUID, not a name; find ids with the list_ tools (get_flow takes a slug). A value outside a fixed set or range is refused; Tools lists the allowed values.

lint_ottl usage errors

deploy_configuration refusals

When one deploy group already serves the configuration, the tool updates it and ignores name; to add a second group, use the fleet's Deploy Groups tab.

get_fleet_install_command refusals

Pipeline tests

run_pipeline_test refuses its inputs

Telflo refuses to start the run

run_pipeline_test returns status: "Running"

The run outlived wait_seconds. Poll get_test_run with the id a few seconds apart until it is Success, Fail, or Error; calling run_pipeline_test again starts a second run. A poll_error means a status read failed during the wait; the run keeps going, so fix the credential if it was a 401, then poll.

The client times out run_pipeline_test

Many clients end a tool call after 60 seconds; the run still finishes, but the agent never gets its id. Set wait_seconds below the client's limit, such as 30, or to 0. A run on a stored version also appears on the editor's Tests sub-tab.

A run ends in Fail or Error

Both are results; see Read the results. A stderr that starts with The test was never executed: means the testing service did not accept or finish the run, for example because the test runner lacks that collector version. Retry later, or use another collector version.

get_test_run_output returns 404

Telflo API error 404: No output for this run yet means the run has not finished or produced no output. Poll get_test_run until the status is final; if there is still no output, read stderr.

A test behaves differently from the fleet

The sandbox runs only the target pipeline, with connectors stripped, so data a connector would pass between pipelines never arrives. Each ${org:...} reference becomes telflo_sandbox_redacted, recorded as an R-105 advisory in the run's mutations; a legacy $orgvar: token is left as written. To test with real values, write them into the YAML and pass it as yaml with configuration_id, which keeps the configuration's collector.

Rate and size limits

See Limits.

Rate limited by the Telflo API

The credential made more than 60 requests in a minute, counting the CLI and scripts on the same credential, and the polling inside run_pipeline_test. Retry after a few seconds, poll a few seconds apart, and give each agent its own service account.

Request body too large or Parse error from the MCP server

HTTP 413 with Request body too large means a request over 2 MB, and HTTP 400 with Parse error a body that is not valid JSON. For the first, shrink the YAML or sample; for the second, update the client or tell its maintainers.

A configuration or sample over 1 MB

Telflo's API accepts bodies up to 1 MB, so a call can still fail with Telflo API error 413: Request body too large. run_pipeline_test checks first: run_pipeline_test: sample_text exceeds 1 MB sends nothing, and request exceeds the 1 MB API limit ... means the sample, rules, and yaml together are too big (any save_rules rules are already saved). Trim the sample to the records the rules need.