Skip to content

Troubleshooting

This page covers common issues and solutions when working with the Records Manager Skill and its documentation.

Documentation Issues

Build Errors

Problem: mkdocs build fails with errors

Common causes and solutions:

  1. Invalid Mermaid syntax 

    # Look for errors like:
# ERROR: Invalid mermaid syntax

# Solution: Check mermaid diagram syntax
# Verify diagram starts with ```mermaid and ends with ```

  2. Broken internal links 

    # Look for errors like:
# WARNING: Documentation file 'xxx.md' not found

# Solution: Update broken link in mkdocs.yml nav section
# Verify file path is correct relative to docs/ directory

  3. Missing images or assets 

    # Look for errors like:
# WARNING: Image 'path/to/image.png' not found

# Solution: Verify image exists in docs/assets/ or use absolute URL

Clean build: 

rm -rf site/
mkdocs build --clean

Local Preview Issues

Problem: mkdocs serve won't start

Port already in use: 

# Try alternative port
mkdocs serve -a localhost:8001

Changes not reflecting:

  • Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)

  • Check file saved in correct location (docs/ directory)

  • Restart server

Blank pages:

  • Check browser console for JavaScript errors

  • Verify Mermaid syntax is correct

  • Try mkdocs build --strict to find errors

Skill Installation Issues

Paperless-ngx Connection Failed

Problem: Error: Failed to connect to paperless-ngx

Solutions:

  1. Verify URL is correct 

    echo $MADEINOZ_RECORDMANAGER_PAPERLESS_URL
# Should include protocol (http:// or https://)

  2. Test paperless-ngx is accessible 

    curl $MADEINOZ_RECORDMANAGER_PAPERLESS_URL
# Should return HTML response

  3. Verify API token 

    # Test token works
curl -H "Authorization: Token $MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN" \
  $MADEINOZ_RECORDMANAGER_PAPERLESS_URL/api/documents/

  4. Check network/firewall

  5. Ensure paperless-ngx URL is accessible from your network
  6. Check if VPN is required
  7. Verify no firewall blocking connections

API Token Authentication Failed

Problem: Error: 401 Unauthorized or Error: 403 Forbidden

Solutions:

  1. Regenerate API token in paperless-ngx:
  2. Go to Settings → Tokens
  3. Create new token with "Read/Write" permissions

  4. Update environment variable

  5. Verify token permissions:

  6. Token must have "Read/Write" access

  7. "Read only" tokens cannot upload documents

  8. Check token format: 

    # Should not have extra quotes or spaces
export MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN="your-token-here"

Environment Variables Not Set

Problem: Commands fail with "undefined" errors

Solutions:

  1. Check if variables are set: 

    echo $MADEINOZ_RECORDMANAGER_PAPERLESS_URL
echo $MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN
echo $MADEINOZ_RECORDMANAGER_COUNTRY
echo $MADEINOZ_RECORDMANAGER_DEFAULT_DOMAIN

  2. Set variables: 

    # Add to ~/.zshrc or ~/.bashrc
export MADEINOZ_RECORDMANAGER_PAPERLESS_URL="https://your-paperless-url.com"
export MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN="your-api-token"
export MADEINOZ_RECORDMANAGER_COUNTRY="Australia"
export MADEINOZ_RECORDMANAGER_DEFAULT_DOMAIN="household"

# Reload shell
source ~/.zshrc  # or source ~/.bashrc

  3. Use .env file (recommended): 

    # Create .env in PAI directory
cat > ~/.claude/.env << EOF
MADEINOZ_RECORDMANAGER_PAPERLESS_URL="https://your-paperless-url.com"
MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN="your-api-token"
MADEINOZ_RECORDMANAGER_COUNTRY="Australia"
MADEINOZ_RECORDMANAGER_DEFAULT_DOMAIN="household"
EOF

Document Upload Issues

Upload Fails with OCR Timeout

Problem: Document uploaded but OCR processing times out

Solutions:

  1. Check paperless-ngx OCR status:
  2. Go to paperless-ngx web UI
  3. Check "Tasks" in left menu

  4. Verify OCR tasks are processing

  5. Wait for OCR to complete:

  6. Large PDFs can take 30-60 seconds
  7. Image-heavy documents take longer

  8. Check document in paperless-ngx UI for "Processing" status

  9. Reduce file size:

  10. Scan at lower DPI (200 DPI instead of 300)
  11. Remove unnecessary pages
  12. Compress PDF before upload

No Tags Suggested

Problem: Document uploaded but no tags applied

Solutions:

  1. Wait for OCR completion:
  2. Tags are applied after OCR finishes
  3. Check document in paperless-ngx UI

  4. Wait 30-60 seconds for processing

  5. Verify document has text:

  6. OCR must extract text from document
  7. Image-only PDFs won't be tagged

  8. Check if document text is selectable in paperless-ngx

  9. Check domain taxonomy: 

    # Verify domain supports document type
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts info \
  --id <document-id>

  10. Manual tagging: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts tag \
  --id <document-id> \
  --tags "manual,tag1,tag2"

Search Issues

Search Returns No Results

Problem: Can't find recently uploaded documents

Solutions:

  1. Wait for OCR processing:
  2. Search works on extracted text
  3. Wait 30-60 seconds after upload

  4. Check document in paperless-ngx UI

  5. Broader search terms: 

    # Try without specific tags
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search \
  --query "invoice" \
  --domain household

# Try just one tag
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search \
  --tags "invoice" \
  --domain household

  6. Check document was uploaded: 

    # List recent documents
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search \
  --query "*" \
  --domain household

Retention Issues

Retention Check Shows Wrong Period

Problem: Documents show incorrect retention periods

Solutions:

  1. Verify country setting: 

    echo $MADEINOZ_RECORDMANAGER_COUNTRY
# Retention varies by country (AU, US, UK)

  2. Check document type:

  3. Different document types have different retention
  4. Tax documents: 7 years in Australia
  5. Medical records: 7 years for tax purposes

  6. Insurance policies: While active + retention period

  7. Update document type: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts tag \
  --id <document-id> \
  --doctype "Tax Return" \
  --domain household

Deletion Issues

Deletion Blocked by Auditor

Problem: Can't delete documents even though retention expired

This is by design - Deletion Auditor requires explicit approval.

Solutions:

  1. Understand the workflow:
  2. Deletion Auditor is a safety feature
  3. Prevents accidental data loss

  4. Requires explicit confirmation

  5. Follow the approval process:

  6. Review what will be deleted
  7. Verify retention periods are truly expired
  8. Check documents aren't needed for audit

  9. Type exact approval phrase when prompted

  10. If you truly need to delete: 

    # The deletion workflow will prompt you
# Read the warning carefully
# Type: "I understand this cannot be undone"
# when you're absolutely certain

Hierarchical Taxonomy Issues

Path Validation Fails

Problem: Error: Invalid path when trying to classify a document

Example: 

❌ Invalid path: HealthManagement/InvalidService/SomeActivity/Document

Solutions:

  1. Use autocomplete to find valid paths: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy autocomplete \
  --domain household \
  --path "HealthManagement/"

  2. Check path structure:

  3. Must have all 4 levels: Function/Service/Activity/DocumentType
  4. Use exact names (case-sensitive)

  5. No spaces around slashes

  6. Browse available functions: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy functions \
  --domain household

Can't Find the Right Document Type

Problem: Don't know which hierarchical path to use for a document

Solutions:

  1. Use keyword search: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy search \
  --domain household \
  --keywords "medical receipt consultation"
    Returns matching paths with relevance scores.

  2. Navigate step-by-step: 

    # Step 1: Get functions
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy functions --domain household

# Step 2: Get services within a function
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy services \
  --domain household \
  --function HealthManagement

# Step 3: Get activities within a service
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy activities \
  --domain household \
  --function HealthManagement \
  --service MedicalCare

# Step 4: Get document types for an activity
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy documenttypes \
  --domain household \
  --path "HealthManagement/MedicalCare/Consultations"

  3. Use fuzzy matching:

  4. Type partial paths: health/med/cons matches HealthManagement/MedicalCare/Consultations
  5. Case-insensitive: HEALTH matches HealthManagement
  6. Autocomplete suggests completions

Hierarchical Tags Not Generated

Problem: Document uploaded but no hierarchical tags applied

Solutions:

  1. Verify hierarchical taxonomy is enabled: 

    const expert = new TaxonomyExpert('AUS', 'household');
console.log(expert.isHierarchicalAvailable());  // Should return true

  2. Check path was provided during upload: 

    # Upload with hierarchical path
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts upload \
  /path/to/document.pdf \
  --domain household \
  --path "HealthManagement/MedicalCare/Consultations/MedicalReceipt"

  3. Manually generate tags for existing document: 

    const tags = expert.generateHierarchicalTags('HealthManagement/MedicalCare/Consultations/MedicalReceipt');
// Apply tags to document via paperless API

Storage Path Generation Fails

Problem: Can't generate filesystem-safe storage path

Solutions:

  1. Validate path first: 

    const validation = expert.validatePath('household', 'HealthManagement/MedicalCare/Consultations/MedicalReceipt');
if (!validation.valid) {
  console.error(validation.reason);
}

  2. Generate storage path from validated hierarchical path: 

    const storagePath = expert.generateStoragePath('HealthManagement/MedicalCare/Consultations/MedicalReceipt');
// Returns: 'Health_Management/Medical_Care/Consultations/Medical_Receipt'

  3. Ensure path has all 4 levels:

  4. Incomplete paths won't generate storage paths
  5. Must specify: Function/Service/Activity/DocumentType

Retention Requirements Unclear

Problem: Don't know how long to keep a document with hierarchical path

Solutions:

  1. Get retention with full hierarchical context: 

    const retention = expert.getRetentionForActivity(
  'household',
  'HealthManagement',
  'MedicalCare',
  'Consultations',
  'Medical Receipt'
);
console.log(retention.legalCitation);  // Shows legal basis
console.log(retention.years);  // Retention period
console.log(retention.reason);  // Why it can't be deleted

  2. Check country-specific retention:

  3. Australia: 7 years for medical expenses (ATO requirement)
  4. United States: Varies by state and document type

  5. United Kingdom: 6 years for tax documents (HMRC requirement)

  6. Verify retention enforcement: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts retention \
  --domain household \
  --path "HealthManagement/MedicalCare/Consultations/MedicalReceipt"

Migration from Flat Taxonomies

Problem: Need to migrate existing flat-tagged documents to hierarchical structure

Solutions:

  1. Follow the migration guide:
  2. See Migration Guide for step-by-step instructions
  3. Automatic mapping for 90%+ of documents

  4. Manual review for edge cases

  5. Check migration status: 

    bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts migration status \
  --domain household

  6. Use dual-mode during transition:

  7. Hierarchical taxonomies support backward compatibility
  8. Flat and hierarchical can coexist during migration period
  9. Legacy queries still work with flat tags

Autocomplete Not Working

Problem: Autocomplete doesn't suggest paths as expected

Solutions:

  1. Check input format:
  2. Use forward slashes: HealthManagement/MedicalCare
  3. No spaces around slashes

  4. Case-insensitive matching supported

  5. Try partial path: 

    # Works with partial matches
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy autocomplete \
  --domain household \
  --path "health"
# Suggests: HealthManagement/...

  6. Verify domain is correct:

  7. Different domains have different taxonomies
  8. household vs corporate vs unit-trust
  9. Check domain supports the function you're searching for

Getting Help

Still Having Issues?

  1. Check the documentation:
  2. Installation Guide
  3. User Guide

  4. Configuration Guide

  5. Search existing issues:

  6. GitHub Issues

  7. Create a new issue: Include:

  8. Your OS and version
  9. paperless-ngx version
  10. Error message (full output)
  11. Steps to reproduce the problem

  12. What you expected to happen

  13. Check paperless-ngx documentation:

  14. paperless-ngx Docs
  15. Many issues are related to paperless-ngx configuration

Common Error Messages

Error Message Cause Solution
Failed to connect to paperless-ngx URL incorrect or service down Verify URL, test connection
401 Unauthorized Invalid API token Regenerate token in paperless-ngx
Document not found Wrong document ID Search for document to find correct ID
No tags suggested OCR not complete or no text Wait for OCR, check document has text
Retention period not found Invalid country or document type Verify country and domain settings
Deletion requires approval Deletion Auditor safety feature Follow approval workflow

Version: 1.2.0 Last Updated: 2026-01-20