Zie619/n8n-workflows · error · HTTPException

Error loading workflow: {str(e)}

Error message

Error loading workflow: {str(e)}

What it means

The catch-all 500 for GET /api/workflows/{filename}: any exception that is not an HTTPException raised while opening and json.load()-ing the matched file is converted to HTTPException(500, 'Error loading workflow: ...'). HTTPExceptions raised earlier in the handler are re-raised untouched (except HTTPException: raise), so this message specifically means an unexpected filesystem or JSON error.

Source

Thrown at api_server.py:367

                            f"Security: Blocked access to file outside workflows: {target_file}"
                        )
                        continue

        if not matching_file:
            print(f"Warning: File {filename} not found in workflows directory")
            raise HTTPException(
                status_code=404,
                detail=f"Workflow file '{filename}' not found on filesystem",
            )

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

        return {"metadata": workflow_meta, "raw_json": raw_json}
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Error loading workflow: {str(e)}")


@app.get("/api/workflows/{filename}/download")
async def download_workflow(filename: str, request: Request):
    """Download workflow JSON file with security validation."""
    try:
        # Security: Validate filename to prevent path traversal
        if not validate_filename(filename):
            print(f"Security: Blocked path traversal attempt for filename: {filename}")
            raise HTTPException(status_code=400, detail="Invalid filename format")

        # Security: Rate limiting
        client_ip = request.client.host if request.client else "unknown"
        if not check_rate_limit(client_ip):
            raise HTTPException(
                status_code=429, detail="Rate limit exceeded. Please try again later."
            )

View on GitHub (pinned to 94007c1445)

Solutions

  1. Read the detail text: it embeds the original exception (e.g. 'Expecting value: line 1 column 1'), which pinpoints parse vs permission problems.
  2. Validate the file: python -c "import json;json.load(open('workflows/<sub>/<file>.json',encoding='utf-8'))".
  3. Fix permissions or ownership so the server process can read the file.
  4. Re-save non-UTF-8 files as UTF-8 and ensure files are written atomically (temp file + rename) to avoid truncated reads.

Example fix

# before
with open(matching_file, 'r', encoding='utf-8') as f:
    raw_json = json.load(f)

# after (explicit friendly errors for the two real failure modes)
try:
    with open(matching_file, 'r', encoding='utf-8') as f:
        raw_json = json.load(f)
except json.JSONDecodeError as e:
    raise HTTPException(status_code=400, detail=f'Invalid JSON in workflow file: {str(e)}')
except OSError as e:
    raise HTTPException(status_code=500, detail=f'Cannot read workflow file: {str(e)}')
Defensive patterns

Strategy: try-catch

Validate before calling

import json, pathlib

def readable_valid_json(path):
    p = pathlib.Path(path)
    if not p.is_file():
        return False
    try:
        json.loads(p.read_text(encoding='utf-8'))
        return True
    except (json.JSONDecodeError, UnicodeDecodeError, OSError):
        return False

Try / catch

try:
    data = client.get(f'/api/workflows/{name}').json()
except HTTPError as e:
    detail = e.response.json().get('detail', '')
    if 'Expecting value' in detail or 'Extra data' in detail:
        flag_file_as_corrupt(name)   # JSON problem
    else:
        flag_file_as_unreadable(name)  # permission/OS problem

Prevention

When it happens

Trigger: open() failing with PermissionError/IsADirectoryError after the existence check raced a deletion; json.load() raising JSONDecodeError on a truncated or BOM-prefixed file; a decode error because the file is not UTF-8 despite being opened with encoding='utf-8'.

Common situations: Concurrently editing workflow JSONs while the server reads them; Windows-encoded or corrupted files committed to the repo; permission changes on the workflows tree under a service account.

Related errors

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