Troubleshooting

Common issues and solutions when using Oculum.

Installation Issues

npm install fails

Problem: npm install -g @oculum/cli fails with permission errors.

Solution:

# Option 1: Use npx (no installation needed)
npx @oculum/cli scan

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @oculum/cli

Command not found

Problem: oculum: command not found after installation.

Solution:

1. Check if installed: npm list -g @oculum/cli
2. Find npm bin: npm bin -g
3. Add to PATH: export PATH="$(npm bin -g):$PATH"

---

Authentication Issues

"Authentication required"

Problem:

Error: Authentication required for verified scans.
Run 'oculum login' to authenticate.

Solution:

# Login via browser
oculum login

# Or use API key
oculum login --api-key ocu_your_key_here

# Or set environment variable
export OCULUM_API_KEY=ocu_your_key_here

"Invalid API key"

Problem:

Error: Invalid API key.

Solutions:

1. Verify key has no extra spaces
2. Check key hasn't been revoked
3. Create a new key at Dashboard Settings

Browser doesn't open

Problem: oculum login doesn't open browser.

Solution:

# Manually open the URL shown in terminal
# Or use API key directly
oculum login --api-key ocu_your_key_here

---

Scanning Issues

No files scanned

Problem:

Scanning...
Files scanned: 0

Solutions:

1. Check you're in the right directory:

   pwd
   ls -la
   

2. Check ignore patterns aren't too broad:

   oculum scan --verbose
   

3. Verify file extensions are supported:

   # Supported: .js, .ts, .tsx, .jsx, .py, .go, .java, .rb, .php
   # Also: .env, .yaml, .json, Dockerfile, etc.
   

Scan hangs

Problem: Scan appears frozen.

Solutions:

1. Try verbose mode to see progress:

   oculum scan --verbose
   

2. Check for very large files:

   # Files over 50KB are skipped
   find . -type f -size +50k
   

3. Reduce scope:

   oculum scan src/ --depth local
   

Out of credits

Problem:

Error: Quota exceeded. You have 0 credits remaining.

Solutions:

1. Check usage:

   oculum usage
   

2. Use local scans (no credits needed for pattern matching):

   oculum scan --depth local
   

3. Upgrade your plan at /pricing

---

Output Issues

Can't see colors

Problem: Output shows escape codes instead of colors.

Solution:

# Disable colors
oculum scan --no-color

# Or pipe to a file
oculum scan > results.txt

Output too long

Problem: Results scroll past screen.

Solutions:

# Use compact mode
oculum scan --compact

# Pipe to less
oculum scan | less -R

# Use quiet mode
oculum scan --quiet

# Output to file
oculum scan --format json --output results.json

JSON parsing fails

Problem: Can't parse JSON output.

Solutions:

# Ensure no extra output
oculum scan --format json --quiet > results.json

# Verify JSON is valid
cat results.json | jq .

---

CI/CD Issues

GitHub Action fails

Problem: Action fails with authentication error.

Solution: Add API key to repository secrets:

1. Go to Settings → Secrets and variables → Actions
2. Add OCULUM_API_KEY secret
3. Update workflow:

   env:
     OCULUM_API_KEY: ${{ secrets.OCULUM_API_KEY }}
   

Exit code issues

Problem: Pipeline fails unexpectedly.

Understanding exit codes:

Solution: Adjust --fail-on threshold:

# Only fail on critical
oculum scan --fail-on critical

# Don't fail on findings
oculum scan --fail-on none

Incremental scan not working

Problem: Incremental scan scans all files.

Solutions:

1. Ensure git is available:

   git --version
   

2. Check you're in a git repository:

   git status
   

3. Specify the base branch:

   oculum scan --diff main
   

---

VS Code Extension Issues

Extension not activating

Problem: Oculum panel not showing.

Solutions:

1. Check extension is installed: Extensions → Search "Oculum"
2. Reload window: Cmd/Ctrl + Shift + P → "Reload Window"
3. Check Output panel for errors: View → Output → Select "Oculum"

Findings not updating

Problem: Panel shows stale findings.

Solutions:

1. Manual scan: Click refresh in Oculum panel
2. Enable auto-scan: Settings → Oculum → Auto Scan On Save
3. Check file is supported (JS, TS, Python, etc.)

Authentication in VS Code

Problem: Can't authenticate in extension.

Solution:

1. Open Command Palette: Cmd/Ctrl + Shift + P
2. Run: "Oculum: Login"
3. Follow browser OAuth flow

---

Performance Issues

Slow scans

Problem: Scans take too long.

Solutions:

1. Use local depth for quick checks:

   oculum scan --depth local
   

2. Ignore unnecessary directories:

   # .oculum.yaml
   ignore:
     - "node_modules/**"
     - "dist/**"
     - "**/*.test.ts"
   

3. Use incremental scans:

   oculum scan --incremental
   

4. Scan specific directories:

   oculum scan src/
   

High memory usage

Problem: Node runs out of memory.

Solutions:

1. Increase Node memory:

   NODE_OPTIONS="--max-old-space-size=4096" oculum scan
   

2. Scan smaller directories:

   oculum scan src/api/
   oculum scan src/lib/
   

---

Common Error Messages

"Rate limited"

Problem:

Error: Rate limited. Please wait before making more requests.

Solution: Wait and retry. Check your plan's rate limits:

"Network error"

Problem:

Error: Network error. Check your internet connection.

Solutions:

1. Check internet connection
2. Check firewall/proxy settings
3. Try again later (service may be temporarily unavailable)

"Unsupported file type"

Problem:

Warning: Skipping unsupported file: example.xyz

Note: This is informational. Oculum only scans code files. See Targeting Files for supported types.

---

Getting More Help

If your issue isn't covered here:

1. Check verbose output:

   oculum scan --verbose
   

2. Check status:

   oculum status
   

3. See Getting Help for contact options

---

Related

• Getting Help — Contact and support options
• CLI Commands — Command reference
• Exit Codes — CI/CD exit codes