Troubleshooting

← Overview · Get started

Start with repo-maintainer check for the native executable, or maintainer check through the Docker wrapper. Both validate YAML without a model call or key. For cloud failures, open the linked Actions run and its retained proposal.

Find the failing stage

Use the diagnosis prompt if you want your coding agent to investigate the retained evidence. Start with the first failing stage, not the final symptom. Keep the original output directory intact.

Stage	Evidence to inspect	Useful next step
Installation or configuration	Command output from --version and check	Fix the executable path, config path or invalid setting before calling a model
Baseline setup/tests	Output from validate	Install the missing project tool or record the pre-existing failure
Agent invocation	report.json, events.jsonl, provider error	Check the selected account/model and whether the process timed out; do not retry blindly
Proposal validation	Retained patch, validation logs and report	Identify the failing check; a patch's existence is not a successful result
PR publication	GitHub Actions publishing job	Check permissions, the selected CI workflow and validation receipt
Scheduling/notifications	Actions run history and observer job	Confirm the caller is on the default branch and that the runner/trigger is available

To inspect local configuration, run these from a terminal, replacing the path:

repo-maintainer --version
repo-maintainer check --repo /path/to/your-repository --json

check makes no model request. validate runs project commands. A workflow dry_run can still call a paid model, so use it only after setup issues are fixed and you intend to generate another proposal. If a run returned blocked, read its retained result before retrying; reducing scope or repairing a check is often more useful than increasing its budget.

Common symptoms

Symptom	What to check
docker or Compose is missing	Install/start Docker with the Compose plugin on the computer running local jobs. Cloud runs do not need local Docker.
Native command or Rust checks are missing	Install the maintainer with cargo install --locked --path . using Rust 1.89 or newer. Add Cargo's binary directory to PATH; install Git and the selected project/agent tools.
Configuration not found	Run from the target repository, use maintainer init, or pass the correct --config path. Cloud config_path is relative to the consuming repo.
Unknown or duplicate YAML field	Compare with the field reference. Settings are validated; misspelled keys are not ignored.
Selected key missing or rejected	Check the provider-specific environment variable/Actions secret. MAINTENANCE_API_KEY (or its legacy SDK alias) overrides builtin provider keys; Codex uses its own auth or CODEX_API_KEY.
Codex/OpenAI/Anthropic rejects the configuration	Set agent.allow_paid: true explicitly, select an available model and supply that provider's key.
Model is unsupported or inaccessible	Groq/Google models must be allowed by the bundled provider profile. For every provider, confirm the selected model is available to your account.
HTTP 429 / quota exhausted	Inspect provider account limits and wait for the relevant reset. Another key in the same quota pool does not add capacity.
Context or request budget exceeded	Narrow the maintenance task or sources. Groq's free token budget needs smaller work; partial proposals are retained.
Source fetch fails	Check that the source is an official HTTPS page, its host is allowed, and it returns readable documentation.
A file cannot be edited	Check editable paths and the proposal boundary. Dependencies/automation may require human help.
Local output permission denied	Prefer the wrapper, which supplies your user ID and creates the output directory. For direct Compose, use a writable bind path and matching UID/GID.
Local changes are missing from a run	Native and Docker runs start from committed HEAD. Commit the source changes you want it to inspect.
Native run does not find a key in .env	Export the key into your shell. Only Docker Compose loads the shared checkout's .env automatically.
Website sign-in or hosted runs are unavailable	The website is a preview; use local execution or GitHub Actions until hosted execution is enabled.
Local run did not open a PR	Local runs generate patches/reports. Configure the weekly cloud workflow for hosted PRs.
Cloud workflow did not start	Merge the caller to the default branch, check Actions settings and try a manual run. GitHub schedules can be delayed.
Run fails immediately with zero jobs	Check reusable-workflow input types. Scheduled events have no manual inputs: pass allow_paid: ${{ inputs.allow_paid == true }}, rather than the missing value. The completion observer can report these failures even when the maintenance workflow cannot start.
PR creation or CI dispatch fails	Check the caller permissions, Actions' PR-creation setting, and that ci_workflow supports manual dispatch.
Checks failed after editing	Review the logs and retained patch. A failed or incomplete proposal does not reach publishing.
No notification arrives	Enable GitHub assignment/mention notifications. Successful no-ops and identical blockers are intentionally quiet.
Codex executable is missing	Install the native CLI on the worker, use install_codex: true in the workflow, or enable it in the Docker build.
A non-Rust repository is trying to run Cargo	Set validation.profile: custom and provide project checks. Omitting validation retains the Rust profile for older configurations.
A project command is missing	Install its runtime on every worker or choose a suitable Docker base image. Custom checks execute the configured argv directly.
Publication lacks a validation receipt	Apply the patch in a fresh checkout, run validate and transfer validation.json with the proposal. Editing patch/config afterwards invalidates it.
Self-hosted jobs stay queued	Check that a live worker matches every label in runner_labels and can access the consuming repository.

Repeatable diagnosis

1. Run repo-maintainer check --repo PATH without credentials to validate configuration.
2. Use the reusable maintenance workflow with dry_run: true to prepare a real proposal and run independent validation without publishing PRs or blocker notifications. A manual dry run may run from a review branch; it reads that branch's configuration but inspects the default branch or existing maintenance PR selected by prepare. Ordinary runs still require the default branch.
3. Inspect repository-maintenance-proposal and the per-job maintenance-diagnostics-<job>-<attempt> artifacts (retained for 30 days). JSONL events contain stage, status, timestamp, elapsed time, run/attempt/job identifiers and a bounded error chain. started without a terminal event indicates interruption, timeout or process termination. Pre-build failures have Actions logs but no CLI event file.
4. Install a separate workflow_run completion observer using the example. It records the original run, revision, job count and failed steps, and fails visibly if maintenance did not succeed. It reads only Actions metadata, never the observed run's code or artifacts. It must be merged to the default branch to receive events.
5. After reviewing the dry-run result, merge the caller and manually run normal maintenance. Confirm the proposal, validation and publishing outcomes before relying on the schedule. unchanged is a successful assessment; it correctly skips validation and publishing when there is no patch.

For local schedulers, set MAINTENANCE_LOG_FILE=/writable/path/events.jsonl. The CLI appends events without changing stdout JSON or command exit status. Use a separate path per run and configure rotation in your scheduler. Known credential environment values are redacted before errors are saved; prompts, environment dumps and raw model responses are not logged. Error messages can still contain repository content or paths, so review logs before sharing. An unwritable log destination prints a warning without masking the real result.

Sharing a useful report

Use the bug report form with the pinned maintainer commit, execution mode, provider/model, expected and actual behavior, and a minimal reproduction. Include a link to a failed run if it is public. Remove API keys, tokens and private repository content from logs and configuration before sharing them.