Docs

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.

AWS Bedrock IAM authentication does not start

🚧

Symptom

INFERENCE_URL points to AWS Bedrock, but STAR does not report that it is generating a token from AWS credentials.

Fix:

  1. Use the documented endpoint format: https://bedrock-mantle.<region>.api.aws/v1.
  2. Remove OPENAI_API_KEY and INFERENCE_TOKEN from the run step rather than defining either variable with an empty value. A configured token takes precedence over IAM, while an empty-but-defined OPENAI_API_KEY can shadow INFERENCE_TOKEN during provider selection.
  3. Confirm that the STAR binary version includes Bedrock IAM support.

See AWS Bedrock Authentication with IAM and OIDC.

No AWS credentials found for Bedrock

🚧

Symptom

STAR reports No AWS credentials found for Bedrock IAM authentication or an AWS credential-resolution error.

Fix:

  • GitHub Actions: add id-token: write and run aws-actions/configure-aws-credentials before STAR.
  • Direct web identity: confirm that AWS_ROLE_ARN is set and AWS_WEB_IDENTITY_TOKEN_FILE exists and is readable.
  • AWS profile: confirm that AWS_PROFILE names an available profile and that the AWS configuration files are mounted on the runner.
  • EC2/ECS: confirm that the instance or task role is attached and that the metadata or container credential endpoint is reachable.

Do not store an OIDC ID token as a long-lived secret. Request it inside the job that runs STAR.

AWS denies the Bedrock role or model request

🚧

Symptom

The log contains AccessDenied, not authorized, or an AssumeRoleWithWebIdentity failure.

Fix:

  1. Check that the IAM role trust policy accepts the actual OIDC issuer, aud, and sub claims from the CI/CD job.
  2. Confirm that the role allows sts:AssumeRoleWithWebIdentity from the configured OIDC provider.
  3. Grant bedrock:InvokeModel for the selected model or inference profile. Add bedrock:InvokeModelWithResponseStream when the endpoint uses streaming responses.
  4. Confirm that the model is enabled and available in the region encoded in INFERENCE_URL.

Restrict the trust policy to the intended repository, ref, pull-request context, or protected CI environment rather than allowing every subject from the OIDC provider.

STAR cannot determine the AWS region

🚧

Symptom

STAR reports Cannot determine AWS region from INFERENCE_URL.

Fix: Use an endpoint containing an explicit AWS region, for example:

https://bedrock-mantle.us-east-1.api.aws/v1

Use the same region in the AWS credentials step, and select a model available in that region.

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.

Azure DevOps repo on a custom domain isn't detected

🚧

Symptom

Your code is on Azure DevOps, but STAR misidentifies the platform — e.g. it reports a GitHub-style owner/repo slug, fails to clone or push, or throws an Invalid GitHub URL / repository-not-found error. This happens when the repository is reached through a custom domain instead of dev.azure.com (a reverse proxy or corporate gateway, or the legacy *.visualstudio.com host).

STAR auto-detects Azure DevOps only when the repository host is exactly dev.azure.com. Any other host falls back to GitHub parsing, so the URL is read with the wrong platform's rules.

Fix: Force the platform explicitly by setting BRIGHT_SCM_PLATFORM=azure-devops on the run step. Also make sure the URL still exposes Azure's coordinates so STAR can parse the organization, project, and repository — the path must contain the _git segment:

  • https://<your-domain>/<org>/_git/<repo>
  • https://<your-domain>/<org>/<project>/_git/<repo>

For authentication, REPO_ACCESS_TOKEN should be an Azure DevOps Personal Access Token with Code (Read & Write) scope (the pipeline's built-in System.AccessToken also works). See BRIGHT_SCM_PLATFORM.

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.

Updated 11 days ago

What’s Next

Did this page help you?