Troubleshooting

Installation issues

`ontoskills install mcp` fails

Check:

Node.js 18+ is available
The release artifacts for the current version exist
Your machine can download GitHub release assets
No proxy or firewall is blocking github.com and api.github.com

Error: “Failed to fetch release metadata”

Network connectivity issue. Check your internet connection and try again. If behind a corporate proxy:

export HTTPS_PROXY=http://proxy.example.com:8080
ontoskills install mcp

Error: “Release does not contain asset”

The platform may not be supported. Check available platforms:

# Supported: darwin-arm64, darwin-x64, linux-arm64, linux-x64
uname -m && uname -s

`ontoskills install core` fails

The compiler requires Python 3.10+:

python3 --version

If Python is installed but not found:

export PYTHON=/path/to/python3
ontoskills install core

Store and package issues

”Package not found”

Check the package ID spelling
Run ontoskills search <query> to discover available packages
If using a third-party store, verify it’s configured:

ontoskills store list

Store skill does not appear in OntoMCP

Skills are enabled by default on install. If a skill is not visible:

Check if it was disabled:

ontoskills list-installed

Re-enable if needed:

ontoskills enable mareasw/greeting/hello

Rebuild the index:

ontoskills rebuild-index

Restart the MCP process

”Skill still not visible after enable”

The MCP server caches the ontology index. Ensure:

Index was rebuilt: ontoskills rebuild-index
MCP server was restarted (close and reopen your AI client)
Check ~/.ontoskills/ontologies/system/index.enabled.ttl exists

Compiler issues

Compiler commands fail

Install the compiler first:

ontoskills install core

Then initialize the ontology foundation:

ontoskills init-core

“ANTHROPIC_API_KEY not set”

The compiler requires an Anthropic API key for LLM-based knowledge extraction:

export ANTHROPIC_API_KEY="your-key-here"
ontoskills compile my-skill

Add to your shell profile (~/.bashrc, ~/.zshrc) to persist.

”SHACL validation failed”

Your skill is missing required fields. Check:

At least one resolvesIntent (in “When To Use” section)
A clear one-line nature statement at the top
Proper YAML frontmatter with name and description

Run with verbose output for details:

ontoskills compile my-skill -v

“Nature not extracted”

Add a clear one-line summary at the beginning of your SKILL.md:

# Skill Title

A brief description of what this skill does.

## What It Does
...

“Missing resolvesIntent”

Ensure your skill has a “When To Use” or similar section:

## When To Use

Use this skill when the user wants to extract text from PDF files.

“Skipping embedding generation”

Embedding generation is optional. The compiler skips it with a warning when ontocore[embeddings] is not installed. To enable semantic search vectors:

pip install ontocore[embeddings]

“Skill has no declared intents”

Every skill must declare at least one intent for semantic search. Add an intents section to your SKILL.md:

## When To Use

- edit spreadsheet
- perform calculation

Import issues

Imported source repo compiled, but the skill still is not visible

Imported skills are enabled by default. If not visible:

Rebuild the index:

ontoskills rebuild-index

Restart the MCP process
If still not visible and the skill was previously disabled, re-enable it:

ontoskills enable <qualified-id>
ontoskills rebuild-index

“Source import failed”

Ensure:

Git is installed and accessible
The repository URL is correct and accessible
OntoCore is installed: ontoskills install core

”No SKILL.md files found”

The import process looks for SKILL.md files in the repository. Ensure:

Files are named exactly SKILL.md (case-sensitive)
Files are in the repository root or subdirectories
Files have valid YAML frontmatter

MCP connection issues

”MCP server not starting”

Check the binary exists and is executable:

ls -la ~/.ontoskills/bin/ontomcp

If missing, reinstall:

ontoskills install mcp

“Connection refused” or “Timeout”

The MCP server may be slow to start. Check:

Server is running: ps aux | grep ontomcp
No port conflicts
Sufficient system resources

”Claude Code cannot find ontomcp”

Ensure ~/.ontoskills/bin is in your PATH, or use the full path in your MCP configuration:

{
  "command": "/home/user/.ontoskills/bin/ontomcp"
}

“ONNX Runtime shared library not found”

The MCP server uses ONNX Runtime for semantic search. If the library is not in your system path:

# Find the library (installed via pip) — platform-agnostic
python3 -c "import onnxruntime; import os; print(os.path.join(os.path.dirname(onnxruntime.__file__), 'capi'))"

Then set the path to the shared library inside that directory:

Platform	Library name
Linux	`libonnxruntime.so`
macOS	`libonnxruntime.dylib`
Windows	`onnxruntime.dll`

# Set the path (example for Linux)
export ORT_DYLIB_PATH=/path/to/libonnxruntime.so

Add to your shell profile (~/.bashrc, ~/.zshrc) to persist.

Index and state issues

”Index corrupted”

Rebuild from scratch:

ontoskills rebuild-index

If that fails, check the lock file:

cat ~/.ontoskills/state/registry.lock.json

“State files missing”

The state directory should contain:

registry.sources.json — configured stores
registry.lock.json — installed packages

If missing, they’ll be recreated on next operation.

”Permission denied” errors

Check ownership of ~/.ontoskills/:

ls -la ~/.ontoskills/

Fix permissions if needed:

chmod -R u+rw ~/.ontoskills/

Diagnostic tools

`ontoskills doctor`

Run a comprehensive health check:

ontoskills doctor

This checks:

MCP binary exists and is executable
Core ontology is valid
Environment variables are set
Index is consistent
Available updates

Verbose output

Most commands support -v for detailed logging:

ontoskills compile my-skill -v
ontoskills install mcp -v

Reset and recovery

Reset everything

To remove the entire managed home:

ontoskills uninstall --all

Warning: This deletes everything under ~/.ontoskills/.

Reinstall from scratch

ontoskills uninstall --all
ontoskills install mcp
ontoskills install core  # if needed
ontoskills init-core     # if needed
# Re-install skills
ontoskills install mareasw/greeting/hello

Getting help

If your issue isn’t covered here:

Run ontoskills doctor and check the output
Search existing issues on GitHub
Open a new issue with:
- ontoskills doctor output
- Command that failed
- Error message
- Your OS and version