Troubleshooting

Start from access, then narrow by release, environment, severity, trace, or issue. Keep the loop evidence-first so humans and AI coding agents can see the same facts before changing code.

Use --json for agent workflows. JSON output is stable enough to parse, quote, and compare between investigation steps.

Fast checks

Problem	Check	Next step
CLI is not logged in	`logbrew status --json`	Run `logbrew login`.
Agent needs auth	`logbrew status --json`	Ask a human to run `logbrew login`, then retry status.
Supported manifest is not detected	`logbrew version --json`	Update through the original install method, then rerun setup from the project root.
No telemetry appears	`logbrew read releases --environment production --json`	Query logs with the same release and environment.
Too many logs appear	`logbrew read logs --severity error --json`	Add release, environment, search, or trace filters.
Trace lookup is empty	Copy `trace_id` from a log or issue	Run `logbrew read trace <trace_id> --json`.
Issue state changed too early	Read issue detail first	Resolve, ignore, or reopen only after collecting evidence.

Secure a compromised account

Choose the smallest scope that matches the incident. A single-session logout ends one refresh-token family. Account-wide logout is destructive across every LogBrew client authorized at or before its returned boundary.

Use account-wide logout when credentials may be exposed beyond one known client. It revokes all account access, browser, and refresh authorizations at or before an inclusive timestamp, ends current live-feed sessions, and clears the browser session cookie.

Choose single-session or account-wide scope

Goal	Endpoint	Scope
End one known client session	`POST /api/auth/logout`	Revokes one refresh-token family. Other account authorizations are not part of this request.
Secure an uncertain or broad compromise	`POST /api/auth/logout-all`	Revokes every account access, browser, and refresh authorization issued at or before the returned inclusive boundary.

Neither endpoint returns a device or session inventory, device names, or counts. They do not claim to revoke provider OAuth grants or sign out of a third-party service.

End one refresh-token family

POST /api/auth/logout does not require bearer authentication. Its body is:

{
  "refresh_token": "<current refresh token>"
}

Build this request inside the client that already holds the current refresh value. Never ask a person or agent to print it, paste it into a shell or ticket, or place it in command history. After success, that client can clear its local credential. This request does not perform account-wide logout.

Revoke every LogBrew login

POST /api/auth/logout-all requires account authentication and has no request body. Do not send a refresh value in the body or expose an authorization header in troubleshooting output.A successful 200 response is:

{
  "revoked": true,
  "revoked_before": "2026-07-16T12:00:00Z",
  "next_action": {
    "code": "clear_local_session",
    "target": "local_credentials"
  }
}

Treat revoked_before as inclusive. Access, browser, and refresh authorizations issued at that timestamp or earlier are rejected. Current live-feed sessions end, and the browser session cookie is cleared. A fresh sign-in completed after that boundary remains valid.

Clear every local credential and sign in again

After account-wide success, every client must remove all locally held LogBrew credentials, discard cached authenticated state, and complete a fresh sign-in. Do this on CLI, browser, mobile, and other clients that used the account. Do not keep an older credential as a fallback.

Recover without exposing auth data

Response	Safe next step
`405`, `code: "method_not_allowed"`	Send `POST /api/auth/logout-all` with account auth. The stable `next` is `send POST /api/auth/logout-all with account auth to revoke every login session`.
`401`	Treat the request as unauthenticated, complete normal sign-in from a trusted client, then retry account-wide logout. Do not include the rejected credential in diagnostics.

If the endpoint still cannot complete, create a private support ticket. Tickets are private to the submitting account and LogBrew support, but reports must omit credentials, refresh values, cookies, authorization headers, hosts, raw logs, customer data, local paths, and source code. Use only the support guide’s strict diagnostic allowlist.

Recover missing first telemetry

Use this order when setup completed but no useful telemetry appears. Stop when one step identifies the mismatch instead of changing multiple inputs at once.

Check API and account access

Confirm the released CLI can reach LogBrew and has account access for reads.

logbrew status --json

If the response says authentication is missing or rejected, a human should run logbrew login, then repeat the status check. Agents must not ask for or print the credential value.

Keep the two credential roles separate

Use an account access credential for CLI and authenticated API reads. Use the project-scoped ingest credential from project setup only for SDK or native telemetry writes.Do not substitute one for the other. Keep both values in local protected configuration, and never echo either value while troubleshooting.

Separate setup acknowledgement from ingest proof

CLI v0.1.24 can record that setup was observed for an existing project:

logbrew projects setup <project_id> --source sdk --environment production --json

A successful response confirms shared setup acknowledgement. It does not prove that an event was accepted. Continue until the ingest response and a matching read both succeed.

Send one safe synthetic log

Use the API URL, project ID, and project-scoped ingest credential already held in local setup variables. Do not print their values. This request sends one placeholder-only info log:

curl -sS "$LOGBREW_API_URL/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "project_id": "$LOGBREW_PROJECT_ID",
  "environment": "production",
  "release": "first-event@1",
  "service_name": "checkout-api",
  "sdk_name": "native-api",
  "sdk_version": "0.1.0",
  "items": [
    {
      "type": "log",
      "data": {
        "severity": "info",
        "message": "first LogBrew event",
        "source": "setup"
      }
    }
  ]
}
JSON

A successful response includes one accepted log. Keep this event free of customer, request, session, or source-code data.

Read back the matching scope

Start with the exact synthetic release and environment, then inspect issue or trace data only when your app emitted those item types.

logbrew logs info --json
logbrew read logs --release first-event@1 --environment production --since 1h --json
logbrew read issues --release first-event@1 --environment production --status unresolved --json
logbrew read trace <trace_id> --json

The synthetic request creates one log, not an issue or trace span. An empty issue result and no trace ID are expected for that request. Use the issue and trace checks for matching telemetry emitted by your app; never invent an ID.

Check correlation values exactly

Confirm the write and read use the same project, release, and environment. Compare the returned service_name with the service that sent the event. If your app sets occurred_at, verify its clock is current UTC and that the read window includes it. Check spelling, case, and whitespace before widening filters.

Recover from a typed error

Follow the returned next value when present. Use these boundaries rather than guessing:

Status	Safe next step
`401`	Run `logbrew status --json`; a human can run `logbrew login` for account reads, while ingest must use the current project-scoped ingest credential.
`403`	Confirm the credential role and that the project belongs to the authenticated account; do not swap or reveal credentials.
`404`	Recheck the project or resource ID against a current account-owned response.
`422`	Correct the required fields or accepted values named by the response, then retry once.
`429`	Stop retry loops and follow the returned quota guidance; do not infer usage from local state.
`5xx`	Do not repeatedly resend an uncertain event. Recheck `logbrew status --json`, wait briefly, and open a support ticket if the failure persists.

If the ordered checks still fail, create a private support ticket. Tickets are private to the submitting account and LogBrew support, never public or visible to other users.Include only the strict diagnostic allowlist: steps, expected, observed, command_name, exit_code, error_code, error_summary, and retry_count. Never include secrets, tokens, credentials, authorization headers, ingest keys, hosts, raw logs, request bodies, payloads, customer data, local paths, or source code.

Fix common problems

Check access first

Verify the CLI can reach LogBrew and identify the current session.

logbrew status --json

If the command says login is needed, run:

logbrew login

Agents should use logbrew status --json to detect missing auth, then ask a human to run logbrew login before continuing.

Confirm release and environment

First-party telemetry must include a non-empty release and environment. Query the same values you send.

logbrew read releases --environment production --json
logbrew read logs --release api@1.2.3 --environment production --json

Use canonical severity

User-facing severity values are info, warning, error, and critical.

logbrew read logs --severity error --json

SDK and runtime aliases are accepted on input, but examples should prefer warning over warn and critical over fatal. API callers should use severity; level remains a compatibility alias. Do not send conflicting severity and level filters in the same request.

Follow the evidence

Read the grouped issue, trace, and matching logs before proposing a fix.

logbrew read issue <issue_id> --json
logbrew read trace <trace_id> --json
logbrew read logs --trace <trace_id> --json

After the cause is clear, update the issue state.

logbrew set issue <issue_id> resolved --json

Quickstart

Follow the first working CLI and telemetry flow.

CLI guide

Use the evidence-first investigation loop.

AI-agent guide

Give coding agents a safe read-first workflow.

Telemetry API

Check API request and response shapes.

Start

Concepts

Workflows

Troubleshooting

Fast checks

Secure a compromised account

Recover missing first telemetry

Fix common problems

Quickstart

CLI guide

AI-agent guide

Telemetry API

​Fast checks

​Secure a compromised account

​Recover missing first telemetry

​Fix common problems

​Related pages

Quickstart

CLI guide

AI-agent guide

Telemetry API

Fast checks

Secure a compromised account

Recover missing first telemetry

Fix common problems

Related pages