Zie619/n8n-workflows · error · HTTPException

Error fetching category mappings: {str(e)}

Error message

Error fetching category mappings: {str(e)}

What it means

A generic 500 from /api/category-mappings. The handler reads context/search_categories.json (returning empty mappings if the file is absent) and builds a filename->category dict; any exception during file read, JSON parse, or iteration over malformed items is re-raised as HTTP 500 with the original error text.

Source

Thrown at api_server.py:689

        if not search_categories_file.exists():
            return {"mappings": {}}

        with open(search_categories_file, "r", encoding="utf-8") as f:
            search_data = json.load(f)

        # Convert to a simple filename -> category mapping
        mappings = {}
        for item in search_data:
            filename = item.get("filename")
            category = item.get("category") or "Uncategorized"
            if filename:
                mappings[filename] = category

        return {"mappings": mappings}

    except Exception as e:
        print(f"Error loading category mappings: {e}")
        raise HTTPException(
            status_code=500, detail=f"Error fetching category mappings: {str(e)}"
        )


@app.get("/api/workflows/category/{category}", response_model=SearchResponse)
async def search_workflows_by_category(
    category: str,
    page: int = Query(1, ge=1, description="Page number"),
    per_page: int = Query(20, ge=1, le=100, description="Items per page"),
):
    """Search workflows by service category (messaging, database, ai_ml, etc.)."""
    try:
        offset = (page - 1) * per_page

        workflows, total = db.search_by_category(
            category=category, limit=per_page, offset=offset
        )

View on GitHub (pinned to 94007c1445)

Solutions

  1. Regenerate context/search_categories.json by re-running the search-category build/reindex step.
  2. Sanity-check the file: python -c "import json;d=json.load(open('context/search_categories.json'));print(type(d), len(d))" — it must be a list of objects.
  3. Read the server log line 'Error loading category mappings:' for the concrete exception, then fix that specific cause (permissions, encoding, structure).
  4. If mappings are non-critical for your client, tolerate an empty result by deleting/renaming the broken file — the handler then returns {"mappings": {}} cleanly.
Defensive patterns

Strategy: fallback

Validate before calling

import json
from pathlib import Path

def mappings_source_ok(path: str = "context/search_categories.json") -> bool:
    p = Path(path)
    if not p.exists():
        return True  # absent file is a supported case (empty mappings)
    try:
        data = json.loads(p.read_text(encoding="utf-8"))
        return isinstance(data, list) and all(isinstance(i, dict) for i in data)
    except (json.JSONDecodeError, OSError):
        return False

Try / catch

try:
    mappings = client.get("/api/category-mappings").json()["mappings"]
except HTTPError as e:
    if e.response.status_code == 500:
        mappings = {}  # client-side filtering still works, just without categories
    else:
        raise

Prevention

When it happens

Trigger: GET /api/category-mappings when context/search_categories.json exists but is corrupt JSON, when an item in the loaded array is not a dict (so .get raises AttributeError), or when the file cannot be opened due to permissions.

Common situations: search_categories.json truncated by a crashed generator; file written with a BOM or wrong encoding so json.load fails; items occasionally being strings instead of objects after a producer change.

Related errors

AI-assisted analysis of Zie619/n8n-workflows@94007c1445 (2026-08-15). Data as JSON: /api/errors/2a5f8a7b200ceb9b. Report an issue: GitHub.