Troubleshooting Guide

August 30, 2026 · View on GitHub

Common issues and solutions when using openlore.

Start here: run openlore doctor. It checks your Node version, git repo, config, index freshness, MCP wiring, and LLM/embedding setup, and prints the exact command to fix anything that is missing.

Installation Issues

CLI Not Found

Problem: openlore command not recognized after install

Solution:

cd openlore
npm install && npm run build && npm link

If npm link requires permissions: sudo npm link

Skill Not Found (Claude Code)

Problem: /openlore command not recognized in Claude Code

Solution:

Verify the skill file exists:
```
ls -la .claude/skills/openlore.md
```
Check file permissions are readable
Restart Claude Code session
Ensure you're in the correct project directory

Permission Denied

Problem: Can't create .claude/skills/ directory

Solution:

mkdir -p .claude/skills
chmod 755 .claude/skills

API Key & LLM Issues

No API Key Found

Problem: No LLM API key found.

Solution: Set one of:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

Only generate, verify, and drift --use-llm require an API key. Commands like analyze, drift, and init work without one.

Custom Endpoint Not Working

Problem: Errors when using --api-base with a local or enterprise server

Solutions:

Verify the URL is valid and includes the version path:

# Correct:
openlore generate --api-base http://localhost:8000/v1

# Wrong (missing /v1):
openlore generate --api-base http://localhost:8000

For self-signed certificates:

openlore generate --api-base https://internal.corp.net/v1 --insecure

Check that the server is running and reachable:
```
curl http://localhost:8000/v1/models
```

Local servers often need a dummy API key:

export OPENAI_API_KEY=dummy-key
openlore generate --api-base http://localhost:8000/v1

SSL Certificate Error

Problem: UNABLE_TO_VERIFY_LEAF_SIGNATURE or similar TLS error

Solution: Use the --insecure flag or set sslVerify: false in config:

openlore generate --insecure

Or in .openlore/config.json:

{
  "llm": {
    "sslVerify": false
  }
}

Warning: This disables SSL verification process-wide. Only use with trusted internal servers.

Wrong Provider Selected

Problem: openlore is using Anthropic when you want OpenAI (or vice versa)

How provider selection works: If ANTHROPIC_API_KEY is set, Anthropic is used. Otherwise, if OPENAI_API_KEY is set, OpenAI is used. To force a specific provider, only set that provider's API key.

Configuration Priority

Settings are resolved in this order (first match wins):

CLI flags (--api-base, --insecure)
Environment variables (OPENAI_API_BASE, ANTHROPIC_API_BASE)
Config file (.openlore/config.json → llm.apiBase, llm.sslVerify)
Provider defaults (https://api.anthropic.com/v1 or https://api.openai.com/v1)

Generation Issues

Invalid Schema for response_format (OpenAI)

Problem: Invalid schema for response_format 'response': schema must be a JSON Schema of 'type: "object"', got 'type: "array"'

Cause: Fixed in v1.2.7. Earlier versions sent top-level type: "array" schemas to OpenAI's structured output API, which requires type: "object" at the root.

Solution: Upgrade to v1.2.7+:

npm install -g openlore@latest

No Domains Detected

Problem: openlore says "Could not identify any domains"

Possible Causes:

Very flat project structure
Unconventional naming patterns
Monolithic codebase without clear separation

Solutions:

Ensure project has some directory structure
Check that source files aren't all in root

Consider manual domain hints in instructions:

/openlore
Consider these domains: user, order, payment

Too Many Domains Generated

Problem: openlore creates specs for every directory

Solution: Add guidance to limit scope:

/openlore
Focus on core business domains only. Ignore utilities, helpers, and infrastructure.

Empty or Minimal Specs

Problem: Generated specs have very few requirements

Possible Causes:

Limited code in analyzed files
Heavy use of external libraries
Generated/compiled code being analyzed

Solutions:

Point to source files, not build output
Ensure .gitignore patterns are respected
Check that high-value files (models, services) exist

Incorrect Requirements

Problem: Generated requirements don't match actual code behavior

This is expected sometimes. Remember: "Archaeology over Creativity" means we should flag uncertainty rather than guess.

Solutions:

Review and edit generated specs manually
Add **Confidence**: Low markers
Remove requirements that can't be verified
File an issue if patterns consistently fail

Format Issues

OpenSpec Validation Fails

Problem: openspec validate --all reports errors

Common Issues:

Missing RFC 2119 keywords

Error: Requirement doesn't use SHALL/MUST/SHOULD/MAY

Fix: Edit requirement to include keyword:

The system SHALL validate email format.

Wrong scenario heading level
```
Error: Scenario must use #### heading
```
Fix: Ensure scenarios use exactly 4 hashtags:
```
#### Scenario: ValidEmail
```

Missing Given/When/Then

Error: Scenario missing required format

Fix: Ensure all three parts exist with bold labels:

- **GIVEN** precondition
- **WHEN** action
- **THEN** outcome

Markdown Rendering Issues

Problem: Specs don't render correctly in viewers

Solutions:

Ensure blank lines before/after code blocks
Check for unclosed formatting (**, `, etc.)
Verify heading hierarchy is correct

Performance Issues

Generation Takes Too Long

Problem: openlore seems stuck or very slow

Possible Causes:

Very large codebase
Too many files being analyzed
Deep directory nesting

Solutions:

Add exclusions for large directories:

/openlore
Exclude: node_modules, dist, build, coverage, .git

Focus on specific directories:

/openlore
Focus on src/core and src/services only

Out of Context Errors

Problem: Claude Code runs out of context during generation

Solutions:

Split into multiple runs by domain
Reduce scope per run
Use the agents.md approach which can work incrementally

Watch Mode Reports a Stale Region

Problem: A watcher debug line reports files as stale, or a recalled anchor has staleRegion: true.

Cause: One edit affected more reverse dependencies than the incremental closure budget can recompute without stalling the watcher. OpenLore recomputes the most structurally significant files first and explicitly marks every deferred file stale. The reported hub/chokepoint counts and top symbol describe the affected region; they do not make a low-significance stale result authoritative.

Solution: Let the scheduled background rebuild converge. If it cannot run, execute:

openlore analyze --reanalyze

The ordering uses fan-in/fan-out from the graph being updated, so it is a best-effort priority signal and may temporarily be a lower bound after recent edits. Files with no usable signal fall back to stable path order. Test callers receive a bounded budget slot so test-to-production reachability is not systematically deferred.

If a closure phase has only one remaining budget slot, it cannot reserve work for both production and test callers. This can happen with an explicitly small closureBudget, or when direct callers consume most of the default budget before Class-P rebind candidates are discovered. OpenLore keeps the highest-significance production caller, and the debug summary discloses that test reachability was deferred.

Drift Detection Issues

No Base Branch Detected

Problem: Could not detect base branch

Solution: Specify the base branch explicitly:

openlore drift --base main
# or
openlore drift --base develop

Too Many False Positives

Problem: Drift detection flags changes that don't affect specs (renames, formatting)

Solution: Use LLM-enhanced mode to filter non-relevant changes:

openlore drift --use-llm

This sends each diff to the LLM for semantic analysis, classifying changes as relevant or not.

Pre-Commit Hook Issues

Problem: Pre-commit hook blocks commits unexpectedly

Solutions:

Check current drift status: openlore drift
Lower the fail threshold: edit the hook to use --fail-on error instead of --fail-on warning
Temporarily bypass: git commit --no-verify (use sparingly)
Remove the hook: openlore drift --uninstall-hook

Drift Not Detecting Changes

Problem: Changed code but no drift reported

Possible causes:

Changes are on the same branch as the base ref
The changed files don't map to any spec domain
The spec was updated alongside the code

Debug: Run with --verbose to see what's being analyzed:

openlore drift --verbose

Integration Issues

Existing OpenSpec Conflict

Problem: openlore overwrites existing specs

Solution: The tool should backup existing files, but you can also:

/openlore
Do not overwrite existing specs. Only create new ones.

Config.yaml Conflicts

Problem: openlore changes break existing config

Solution: Review changes before accepting:

/openlore
Show me what you would add to config.yaml before making changes.

Getting Help

Debug Mode

Set DEBUG=1 for stack traces on errors:

DEBUG=1 openlore generate

Still Stuck?

Check the docs:
- Philosophy — Understanding the approach
- OpenSpec Format — Format reference
- Architecture — Internal design
- OpenSpec Integration — Ecosystem integration
File an issue on GitHub:
- Include: Project type, error message, relevant code structure, Node.js version
- Don't include: Sensitive code, API keys, or credentials
Try manual approach:
- Use the spec format reference
- Write specs manually for problematic areas
- Let openlore handle the clearer parts

Known Limitations

Language Support
- Best: JavaScript/TypeScript
- Good: Python
- Basic: Go, Rust, Java
- Limited: Other languages
Framework Detection
- Well-supported: Express, NestJS, FastAPI, Django
- Partial: Many others
- Detection is heuristic-based
Complex Architectures
- Microservices: May need per-service runs
- Monorepos: Focus on specific packages
- Plugin systems: May miss dynamic behavior
Dynamic Behavior
- Runtime configuration not detected
- Reflection/metaprogramming may be missed
- Database-driven logic not captured