Logging & Troubleshooting

Logging & diagnostics

STAR keeps the console quiet and clean by default:

• Console (stdout): high-level phase milestones and concise, actionable errors only.
• Log file: every run writes a full, verbose diagnostic log to ~/.bright-agent/logs/run-<timestamp>.log. The console prints the exact path at startup. Share this file with Bright support if you hit an issue.
• Secret redaction: tokens and credentials (BRIGHT_TOKEN, REPO_ACCESS_TOKEN, OPENAI_API_KEY, INFERENCE_TOKEN, Authorization/Bearer/Set-Cookie values) are redacted from all log output, including the log file.
• BRIGHT_DEBUG=1: mirrors the full diagnostic log to the console — useful for live debugging in CI. Set it as an environment variable on the run step.

Usage dumping (cost & token analysis)

For offline cost and token-usage analysis, STAR can persist every raw LLM request/response turn to disk. This is off by default — enable it only for debugging spend, tuning prompts, or auditing model behavior, not for normal runs.

• Enable: set BRIGHT_DUMP_TURNS to a truthy value (1, true, yes, or on).
• Where it writes: <BRIGHT_DUMP_DIR>/<run-uuid>/<NN-label>/turns.jsonl — each run gets its own UUID subdirectory (default base: <cwd>/.tmp), and each prompt conversation lands in its own indexed subfolder.
• What it contains: raw request/response turns in JSON Lines format, for offline token/cost analysis per phase and model. At runtime, STAR also prints a per-phase and total token report to the log (the [Tokens] lines).

Collect it in CI (GitHub Actions example):

- name: Run Bright Agent
  env:
    BRIGHT_DUMP_TURNS: "1"
    BRIGHT_DUMP_DIR: "${{ runner.temp }}/bright-dumps"
  run: ./bright-agent

- name: Upload LLM turn dumps
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: bright-llm-turns
    path: ${{ runner.temp }}/bright-dumps

Common issues

Scan can't reach the app on localhost

🚧

Symptom

The scan can't connect to your app on localhost, most often on CircleCI or GitLab.

Some CI executors run Docker on a separate host from the job, so a container started by STAR isn't reachable on localhost.

Fix:

• CircleCI — use the machine executor, not docker with setup_remote_docker.
• GitLab — use a runner that runs Docker on its own host, or a docker executor with docker-in-docker configured.

See Prerequisites.

Binary got committed into the fix PR

🚧

Symptom

The STAR binary (or a SARIF file) shows up as a committed file in the fix pull request.

STAR commits with git add -A, so anything inside the checkout gets included.

Fix: Always download the binary (and any SARIF file) outside the checkout — e.g. the runner's temp directory — as shown in every CI template.

Run needs a value STAR can't guess

🚧

Symptom

A run can't finish because the app needs a value (a secret, a config option, an environment detail) that STAR can't infer.

Fix: STAR posts a PR comment explaining what's missing. Reply with /bright-agent <guidance> to steer the next run — see Comment Steering.

404 not_found_error with your model name (0 API calls)

🚧

Symptom

The log shows a 404 "not_found_error" with your model name (e.g. model: gpt-5.4-mini) and the run fails with 0 API calls.

AI_MODEL is set to a model name that your inference provider doesn't serve. This typically happens when INFERENCE_URL points at one provider (e.g. Anthropic, Ollama, a self-hosted gateway) but AI_MODEL still contains a model name from a different provider (e.g. an OpenAI model name).

Fix: Set AI_MODEL to a model your provider actually offers — for example claude-sonnet-4-20250514 for Anthropic, or check your provider's model list. A comma-separated escalation chain (e.g. claude-sonnet-4-20250514,claude-opus-4-20250514) also works.

403 "GitHub Actions is not permitted to create or approve pull requests"

🚧

Symptom

The log shows Failed to create PR: 403 "GitHub Actions is not permitted to create or approve pull requests".

The built-in GITHUB_TOKEN doesn't have permission to open PRs by default.

Fix: Go to Settings → Actions → General → Workflow permissions and check "Allow GitHub Actions to create and approve pull requests". Alternatively, use a Personal Access Token (with repo scope) as REPO_ACCESS_TOKEN instead of relying on GITHUB_TOKEN.

Fix commits don't trigger other CI workflows

🚧

Symptom

STAR's fix commits/PRs don't kick off your other pipelines.

This is a platform anti-recursion rule, not a STAR limitation: commits/PRs made with GITHUB_TOKEN (GitHub) or System.AccessToken (Azure DevOps) don't trigger other pipelines.

Fix: Use a personal access token as REPO_ACCESS_TOKEN if you need the fix push to run your CI.

Run stopped partway through in CI

🚧

Symptom

A run ends before completing, typically because the CI job hit its time limit.

Fix: STAR watches your CI job's timeout (BRIGHT_CI_TIMEOUT_MINUTES, auto-detected on GitHub Actions) and saves progress to BRIGHT_STAR.md before the runner is killed, with BRIGHT_TIMEOUT_MARGIN_MINUTES of headroom (default 3 minutes). The next run picks up from that saved state instead of starting over. See Configuration.

Build fails with an out-of-space error

🚧

Symptom

A build fails with a disk / out-of-space error (e.g. ENOSPC).

Fix: STAR fails fast with a clear message when free disk drops below MIN_FREE_DISK_MB (default 2048 MB) after reclaiming unused Docker artifacts, instead of crashing mid-build. Free up runner disk or raise the runner's disk size.

Validate your setup before a real run

📘

Goal

You want to confirm configuration and access tokens are correct before launching a full scan.

Fix: Set BRIGHT_PREFLIGHT_ONLY=1 to run STAR's local preflight, which checks core configuration and access tokens without starting a scan.

Still stuck?

Send the redacted log from ~/.bright-agent/logs/ to Bright support.