Troubleshooting

Version: 4.1 | Last updated: 2026-10-29

Setup is four steps on the happy path (Get started). This page covers what to do when a step reports a problem, stalls, or behaves in a way the short version doesn't describe. For sign-in, CLI install, and account questions, see the FAQ.

Telemetry isn't arriving

Bluebox checks for telemetry and marks the instrumentation step complete once it arrives. If nothing arrives, check that your service exports telemetry, that the endpoint and ingest-token line are where the service reads its environment, and that you redeployed after adding them.

If your services appear in Bluebox but no traces, logs, or events have arrived yet, the step says so directly. Your connection is fine and your services are visible; they have not sent any telemetry yet, so there is no need to instrument them again.

Occasionally the step reports that Bluebox could not check for telemetry at this time. That means the check itself did not complete, not that your services are sending nothing. No action is needed: Bluebox retries on its own, and the step is not counted as outstanding work while the answer is unknown.

Where Bluebox has no way to read your data back, the step reports that the endpoint accepted your ingest token without confirming that records arrived. Telemetry can still be flowing; Bluebox just cannot query it yet.

Once the Setup page shows your endpoint and token, apply them to your service configuration and run or redeploy. Bluebox waits for telemetry data before marking this step complete, and the checklist reports your setup as finished only once it has arrived.

Your ingest token

Workspace owners can copy the token at any time, also after a rotation. On the Setup page, select Instrument your services. Next to Ingest token, click the copy icon (Copy token) to copy the token without showing it on screen, or the eye icon (Reveal token) to show it. If you aren't a workspace owner, ask one for access. If the section says Bluebox can't create an ingest token for a manually-connected backend, paste the ingest token you created in your monitoring environment into the Workspace OTLP ingest token field in the observability backend step, re-check, then copy it as above. Bluebox sends a test log, metric, and trace with the pasted token before saving it. If any is rejected, the token isn't saved, and when a scope is missing the message names it. Bluebox keeps the result of its latest check with the token. If that check found the token can't send telemetry, a warning appears under the revealed token naming the rejected signal and, when known, the missing scope; rotate the token or paste one that works.

If you need to issue a fresh ingest token (say the current one may have been exposed), a workspace owner can rotate it from the Setup page when the observability connection was set up automatically. On connections configured by hand, Rotate is disabled, because rotation relies on the credentials created during automatic setup. Rotating revokes the previous ingest token, and the revoke can take a short time to stop ingest, so update any running instrumentation with the new value right away. A token you pasted yourself is revoked only when Bluebox can read its ID from the token; otherwise it stays valid, so revoke it in your monitoring environment. On a connection configured by hand, Bluebox never revokes a token you pasted; revoke it in your monitoring environment when you no longer need it. The new token appears right away; Bluebox then verifies telemetry ingest in the background and shows progress under the token until it is confirmed.

If rotating or creating the token fails because the observability backend's token limit is reached, your monitoring account already holds as many tokens as it allows. Your current ingest token keeps working. Revoke tokens you no longer use in your monitoring environment, then try again.

Ingest tokens that Bluebox creates don't expire unless an expiry is requested when the token is rotated. An older token that Bluebox created still expires 90 days after it was issued, and a token you created yourself expires whenever you set it to. Rotate an older token once to replace it with one that doesn't expire. For a token with an expiry date, Bluebox warns you before it expires. From 14 days before the expiry date, a warning appears in three places: the notifications tray behind the bell in the top bar, a badge on the Setup link in the left sidebar, and a banner on the Setup page itself, with a matching callout beside the token in the instrumentation step. Once the date passes, the same three places switch to an error, because telemetry ingestion has stopped at that point. Only a workspace owner sees these warnings: rotating the token is the only remedy, and a plain member cannot perform it, so the warning is not shown to them. The warning is deliberately not dismissible and clears on its own once the token is rotated. If Bluebox has no expiry date on record for your token, it stays silent rather than guessing.

The observability backend connection

The Setup page shows your OpenTelemetry endpoint and ingest-token header when they are ready. If Bluebox is still preparing those values, leave the page open; they appear automatically after a few minutes. If Setup says it needs attention, or bluebox otlp-endpoint informs you that manual configuration is necessary, a workspace owner should update the saved connection or connect a monitoring backend with the required access before trying again.

When your workspace is created, Bluebox starts preparing the observability connection automatically when it has the information it needs.

If you're not a workspace owner, the Setup page still shows the connection status correctly once it's ready; you see a read-only summary instead of the connection form, since only workspace owners can change it. If the workspace's connection is managed by another member who has not shared it with you, the Setup step shows "Managed by another member" and the instrumentation step explains this instead of showing the endpoint and ingest token. Ask that member to share the connection with you.

If the platform token used for the observability connection is approaching its expiry date or has already expired, the Setup page shows a warning or error banner at the top and a callout inside the connection step, and the Setup link in the left sidebar shows a warning badge. This also works for a platform token you created and pasted yourself: Bluebox reads its expiry date from your observability platform when you save it and checks it again about once a day, so a date you change there shows up in Bluebox within a day. If the date Bluebox has on record has passed, it checks the token once more before blocking an investigation, so a token you extended keeps working right away and its new date shows up at once. If Bluebox can't read a token's expiry date, it shows no expiry warning for that token. An expired token blocks new investigations. A workspace owner can paste a fresh runtime token into the connection step. If your Setup page shows no connection step, or if you can't create a new token, email Bluebox support at support@bluebox.ai.

Less often, Setup reports that the read access token for your workspace could not be created. The workspace is otherwise connected, and telemetry can still arrive, but Bluebox cannot read your observability data until read access is restored. This one is not something you can fix from the Setup page, so the page asks you to email Bluebox support at support@bluebox.ai with your workspace name. If instead Setup reports that read access could not be confirmed, access is often still finishing setup—re-open the Setup page after a few minutes to re-check, and email support if it stays unconfirmed.

Wiring instrumentation by hand

Your coding agent wires the OpenTelemetry SDK to your language and framework and takes the OTLP endpoint from your environment, or from bluebox otlp-endpoint. When it finishes, it leaves a readable record of the run in .bluebox/instrumentation-run.md, which git ignores. To wire things up yourself instead, run bluebox otlp-endpoint and set the endpoint as OTEL_EXPORTER_OTLP_ENDPOINT in your service's environment.

Earlier CLI versions wrote a .env.otel.bluebox-template file into your repositories. The next time you save bluebox setup, Bluebox deletes each copy it wrote that you have not changed. It keeps a copy you edited or committed to git, and setup names each kept file in a warning. Delete those yourself if you no longer need them.

The agent's closing summary lists each deployed target it found — a Helm chart, a Kubernetes manifest, an AWS serverless template — with where that target's endpoint and token go and the environment name to give it. When it could verify telemetry only on your machine, the summary says so and ends with the bluebox ask command to run once that target is deployed.

GitHub repositories

If a repository you expect is not in the list, Bluebox has not been authorized for the organization or account that owns it. Select Configure the Bluebox GitHub App, pick that organization or account, grant access to the repository, and confirm. You are returned to this page with the repository now listed.

If you selected the repository on GitHub but it still does not appear, and you are not an owner of the organization that owns it, GitHub marks your selection with a request badge instead of granting it immediately: an organization owner has to approve the request in the organization's installed GitHub Apps settings before Bluebox can see the repository.

From another person's personal GitHub account, Bluebox lists only the repositories they added you to as a collaborator, even when the Bluebox GitHub App is installed on their whole account.

Each repository shows its visibility as GitHub reports it: Public, Private, or Internal. Internal repositories exist only in organizations owned by a GitHub Enterprise Cloud account. Bluebox reads the code in every repository you select. It files issues, comments, pull requests, and labels only in private and internal repositories. When writes to public repositories are turned on for your workspace (for example, during a workshop), it files in public repositories too, and anyone can read what it files there. Visibility unknown means the picker couldn't confirm a repository's visibility. Unless writes to public repositories are turned on, Bluebox writes there only if GitHub confirms the repository isn't public.

When you select a public repository, a warning above the confirm button says that anyone can read the issues, comments, and pull requests Bluebox posts there. A repository with unknown visibility gets a warning too, since it may be public. Neither warning stops you from selecting the repository.

When a public repository is connected, every workspace member gets a notification that says who connected it, that anyone can read what Bluebox posts there, and links to Settings → Setup.

If a connected repository becomes public on GitHub later, workspace owners get a notification that names it and says anyone can read what Bluebox posts there, and Settings → Setup shows the same news above the repository list. Dismissing that alert also clears the notifications.

Invitations and membership

If a workspace has already reached its member limit, Bluebox tells you the invitation can't be accepted until a seat frees up, rather than failing with a generic error. If the invitation has expired, was revoked, or was already used, Bluebox says so instead of leaving you guessing. A workspace owner can revoke a pending invitation or remove a member to free a seat, then invite you again — see Workspaces.

Still stuck

Email Bluebox support at support@bluebox.ai with your workspace name, or see Get help for where to report bugs and ask questions.