Troubleshooting

“loading index (run ‘certify scan’ first)”

The unit index doesn’t exist yet:

certify scan

“No certification records found”

Run certification before generating reports:

certify certify --skip-agent

“no configured submodules found”

In workspace mode, each submodule needs certify init:

certify init --workspace

Architect review: LLM timeout

Large models on local hardware can take several minutes per phase. The architect command uses a 10-minute timeout per phase. If your model is slower:

• Use a smaller model: certify architect --model qwen3:8b
• Run single phases: certify architect --phase 1
• Use a cloud provider with faster inference

Architect review: fabricated metrics

If the LLM invents numbers not present in the snapshot, this usually means you’re using a model that doesn’t follow grounding instructions well. Try:

• A larger model (30B+ parameters follow instructions better)
• A code-specialized model (e.g., qwen/qwen3-coder-30b)
• Run certify certify first to ensure the snapshot has real data

Agent review: 429 Too Many Requests

Free-tier models on OpenRouter have rate limits.

• Use --batch 20 to process fewer units per run
• Wait a few minutes between runs (the queue saves progress)
• Set up a paid fallback model in config
• Use --skip-agent for deterministic-only certification

Agent review: 401 Unauthorized

Your API key is invalid or not set:

export OPENROUTER_API_KEY=sk-or-v1-your-key-here

For CI, add OPENROUTER_API_KEY as a GitHub repository secret.

Agent review: 402 Payment Required

Account budget exhausted on OpenRouter. The system will:

1. Abort the current model
2. Try free-tier fallback models
3. Skip agent review if all models fail

Certification continues with deterministic evidence only.

All units show the same score

This usually means no language-specific evidence was collected. Check:

1. Is go.mod present? (needed for Go tools)
2. Is go in PATH?
3. Run certify scan to verify language detection
4. Check output for “Collected N repo-level evidence items”

Queue stuck / old state

Reset the queue to start fresh:

certify certify --reset-queue

“go vet” or “golangci-lint” not found

These tools are optional. Without them, the system uses available evidence. Install for better results:

# golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh

Records directory too large

Each unit gets a small JSON file (~500 bytes). For very large repos (10k+ units):

1. Add .certification/records/ to .gitignore
2. Use CI artifacts instead of committed records
3. Scope certification to critical paths via scope.include

Workspace: 0 units discovered in a submodule

Check that the submodule has:

1. certify init run (.certification/config.yml exists)
2. Source files not excluded by scope.exclude
3. An empty scope.include: [] means “include nothing” — remove it to include everything

Diagnose with Doctor

Before filing an issue, run the built-in diagnostics:

certify doctor

This checks your environment, project setup, configuration, policies, tools, and AI providers — showing exactly what’s working and what needs attention.

Getting Help

• Run certify doctor to diagnose setup issues
• Run certify onboard to see what steps remain
• GitHub Issues
• certify --help for command reference
• certify <command> --help for flag details