Troubleshooting

Solutions to common issues with ctxloom.

Installation Issues

Command Not Found

Problem: ctxloom: command not found

Solutions:

1. Ensure Go bin is in PATH:

export PATH=$PATH:$(go env GOPATH)/bin

2. Reinstall from source:

git clone https://github.com/ctxloom/ctxloom.git
cd ctxloom
go generate ./...
go install .

3. Verify installation:

which ctxloom
ctxloom --version

Build Errors

Problem: Build fails with dependency errors

Solution:

go clean -modcache
go mod download
go generate ./...
go install .

macOS Issues

”Cannot be opened” or “Unverified developer”

Problem: macOS blocks ctxloom with messages like:

• “ctxloom cannot be opened because it is from an unidentified developer”
• “ctxloom cannot be opened because Apple cannot check it for malicious software”

This happens because ctxloom binaries are not code-signed or notarized with Apple (common for open-source CLI tools).

Solution 1: Remove quarantine attribute (Recommended)

xattr -d com.apple.quarantine /usr/local/bin/ctxloom

Solution 2: Allow via System Settings

1. Try to run ctxloom - it will be blocked
2. Open System Settings → Privacy & Security
3. Find the blocked app message and click “Open Anyway”
4. Confirm in the dialog

Solution 3: Build from source

git clone https://github.com/ctxloom/ctxloom.git
cd ctxloom
go generate ./...
go install .

Shell completion not loading on macOS

Problem: Bash completions don’t work after installation

Solution: Ensure bash-completion is installed:

brew install bash-completion

Add to ~/.bash_profile:

[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

Then install the completion:

ctxloom completion bash > /usr/local/etc/bash_completion.d/ctxloom

Context Not Injected

Hooks Not Applied

Problem: Context doesn’t appear in Claude Code sessions

Check hooks configuration:

cat .claude/settings.json | jq '.hooks'

Expected output:

{
  "SessionStart": {
    "hooks": [
      {
        "type": "command",
        "command": "ctxloom hook inject-context <hash>"
      }
    ]
  }
}

Fix:

ctxloom init

Context File Missing

Problem: Hook runs but no context appears

Check context file:

ls -la .ctxloom/context/

Regenerate:

ctxloom init

Wrong Directory

Problem: ctxloom not finding configuration

Check you’re in the right directory:

# Should show your .ctxloom directory
ls -la .ctxloom/

# Or initialize if missing
ctxloom init

Remote Issues

Authentication Failed

Problem: 401 Unauthorized or 403 Forbidden when accessing remotes

Solution - Set authentication token:

# GitHub
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# GitLab
export GITLAB_TOKEN=glpat-xxxxxxxxxxxx

Verify token:

# Test GitHub access
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Rate Limiting

Problem: 403 rate limit exceeded

Solutions:

1. Set authentication token (increases rate limit):

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

2. Wait for rate limit reset (usually 1 hour)

3. Check current rate limit:

curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

Remote Not Found

Problem: remote not found: myremote

Check configured remotes:

ctxloom remote list

Add the remote:

ctxloom remote add myremote owner/repo

Sync Failures

Problem: ctxloom remote sync fails

Debug:

# Check what's being synced
ctxloom remote sync --dry-run

# Sync with verbose output
CTXLOOM_VERBOSE=1 ctxloom remote sync

# Force re-sync
ctxloom remote sync --force

Profile Issues

Profile Not Found

Problem: profile not found: myprofile

List available profiles:

ctxloom profile list

Check profile location:

ls .ctxloom/profiles/
ls ~/.ctxloom/profiles/

Circular Inheritance

Problem: circular profile inheritance detected

Check profile parents:

ctxloom profile show myprofile

Fix: Remove circular parent references in profile YAML.

Missing Bundles

Problem: Profile references bundles that don’t exist

Check what bundles are available:

ctxloom fragment list

Install missing bundles:

ctxloom fragment install remote/missing-bundle

Fragment Issues

Fragment Not Found

Problem: fragment not found: myfrag

List available fragments:

ctxloom fragment list
ctxloom fragment list --bundle mybundle

Check fragment reference format:

# Correct formats:
ctxloom fragment show mybundle#fragments/fragname
ctxloom fragment show fragname  # searches all bundles

YAML Parse Error

Problem: failed to parse bundle: yaml error

Validate YAML syntax:

# Use a YAML linter
yamllint .ctxloom/bundles/mybundle.yaml

# Or try loading the bundle
ctxloom fragment list --bundle mybundle

Common YAML issues:

• Incorrect indentation (use spaces, not tabs)
• Missing quotes around special characters
• Improper multiline string syntax

Content Too Large

Problem: warning: assembled context is 24KB (recommended max: 16KB)

Solutions:

1. Distill verbose fragments:

ctxloom fragment distill mybundle

2. Use fewer fragments:

# Check what's included
ctxloom run --dry-run --print | wc -c

3. Create focused profiles:

# Instead of one large profile, create task-specific ones
# api-dev.yaml - only API-related fragments
# testing.yaml - only testing fragments

MCP Server Issues

Server Won’t Start

Problem: ctxloom mcp serve fails

Check for port conflicts:

# MCP uses stdio, but check for other issues
ctxloom mcp serve 2>&1 | head -20

Verbose mode:

CTXLOOM_VERBOSE=1 ctxloom mcp serve

Tools Not Appearing

Problem: MCP tools don’t show up in Claude Code

Check MCP configuration:

cat .claude/settings.json | jq '.mcpServers'

Ensure ctxloom is registered:

ctxloom mcp auto-register --enable
ctxloom init

Restart Claude Code after configuration changes.

Tool Execution Fails

Problem: MCP tool returns error

Check ctxloom logs:

# Run MCP server with verbose logging
CTXLOOM_VERBOSE=1 ctxloom mcp serve

Test tool directly:

# Test the underlying CLI command
ctxloom fragment list
ctxloom profile list

Performance Issues

Slow Context Assembly

Problem: ctxloom run takes a long time

Diagnose:

time ctxloom run --dry-run

Solutions:

1. Reduce fragment count - use fewer, more focused fragments
2. Use distillation - smaller fragments load faster
3. Check disk I/O - ensure .ctxloom/ isn’t on slow storage

Slow Remote Operations

Problem: Remote sync/browse is slow

Solutions:

1. Check network - ensure good connectivity to GitHub/GitLab
2. Use caching - ctxloom caches remote content locally
3. Reduce scope - sync specific profiles instead of all:

ctxloom remote sync --profiles myprofile

Configuration Issues

Config Not Loading

Problem: Configuration changes not taking effect

Check config location:

# Project config
cat .ctxloom/config.yaml

# User config
cat ~/.ctxloom/config.yaml

Validate config:

# Use a YAML linter
yamllint .ctxloom/config.yaml

# Or test by showing config
ctxloom config show

Environment Variables Not Working

Problem: Environment variables aren’t being used

Check variable is set:

echo $MY_VARIABLE

Check variable syntax in templates:

# Correct
content: "API key: {{API_KEY}}"

# Wrong
content: "API key: $API_KEY"

Getting Help

Debug Mode

Enable verbose output for any command:

CTXLOOM_VERBOSE=1 ctxloom <command>

Check Version

Ensure you’re on the latest version:

ctxloom --version

# Update from source
cd ctxloom
git pull
go generate ./...
go install .

Report Issues

If you’ve tried the above and still have issues:

1. Gather information:

ctxloom --version
go version
uname -a

2. Create minimal reproduction

3. File issue: https://github.com/ctxloom/ctxloom/issues

Include:

• ctxloom version
• Operating system
• Steps to reproduce
• Expected vs actual behavior
• Relevant configuration (sanitized)