What causes "Illegal custom path" in binary-husky/gpt_academic?

Set CUSTOM_PATH to a string starting with '/', e.g. CUSTOM_PATH = "/gpt-academic".

binary-husky/gpt_academic · error · RuntimeError

Illegal custom path

Error message

Illegal custom path

What it means

Raised by the Gradio launch helper in toolbox.py:708 when the CUSTOM_PATH setting fails the is_path_legal check. is_path_legal only accepts a non-empty string beginning with '/' (with an optional extra '/' segment for sub-paths); anything else — no leading slash, an empty string, a non-string value — logs 'illegal custom path' and returns False, and the caller converts that into RuntimeError('Illegal custom path') before mounting the app.

Source

Thrown at toolbox.py:708

                "illegal custom path: {}\npath must not be empty\ndeploy on root url".format(
                    path
                )
            )
            return False
        if path[0] == "/":
            if path[1] != "/":
                logger.info("deploy on sub-path {}".format(path))
                return True
            return False
        logger.info(
            "illegal custom path: {}\npath should begin with '/'\ndeploy on root url".format(
                path
            )
        )
        return False

    if not is_path_legal(custom_path):
        raise RuntimeError("Illegal custom path")
    import uvicorn
    import gradio as gr
    from fastapi import FastAPI

    app = FastAPI()
    if custom_path != "/":

        @app.get("/")
        def read_main():
            return {"message": f"Gradio is running at: {custom_path}"}

    app = gr.mount_gradio_app(app, demo, path=custom_path)
    uvicorn.run(app, host="0.0.0.0", port=port)  # , auth=auth

def auto_context_clip(current, history, policy='search_optimal'):
    if policy == 'each_message':
        return auto_context_clip_each_message(current, history)
    elif policy == 'search_optimal':

View on GitHub (pinned to d6bde0fa54)

Solutions

Set CUSTOM_PATH to a string starting with '/', e.g. CUSTOM_PATH = "/gpt-academic".
If you want root deployment, explicitly set CUSTOM_PATH = "/" or remove/empty the override so the default root path is used.
Check config_private.py and environment variables for a CUSTOM_PATH value with whitespace, quotes, or a full URL, and normalize it to a bare absolute path.
Restart the app after fixing the config; the check re-runs at startup.

Example fix

# before (config_private.py)
CUSTOM_PATH = "gpt-academic"  # RuntimeError: Illegal custom path

# after
CUSTOM_PATH = "/gpt-academic"

Defensive patterns

Strategy: validation

Validate before calling

def normalize_custom_path(p):
    if p is None:
        return '/'
    p = str(p).strip()
    if not p.startswith('/'):
        p = '/' + p.lstrip('/')
    return p or '/'

CUSTOM_PATH = normalize_custom_path(CUSTOM_PATH)
assert CUSTOM_PATH.startswith('/'), 'custom path must begin with /'

Type guard

def is_legal_path(p) -> bool:
    if not isinstance(p, str) or not p.startswith('/') or len(p) == 0:
        return False
    return True

Try / catch

try:
    from toolbox import run_gradio  # or the launch helper containing the check
    run_gradio(demo, port=PORT, custom_path=CUSTOM_PATH)
except RuntimeError as e:
    if 'Illegal custom path' in str(e):
        sys.exit('CUSTOM_PATH must start with "/" (e.g. "/gpt-academic"). Fix config_private.py.')
    raise

Prevention

Always write CUSTOM_PATH with a leading slash and no scheme/host: '/gpt-academic', never 'gpt-academic' or a full URL.
Set CUSTOM_PATH explicitly to '/' for root deployments instead of leaving it empty or None.
Validate CUSTOM_PATH in your deployment script before launching the app.

When it happens

Trigger: Setting CUSTOM_PATH = "gpt-academic" (missing leading '/'), CUSTOM_PATH = "" or leaving it unset in a way that yields an empty string, or CUSTOM_PATH = None / a non-string, then starting the Gradio server which calls this setup path. The check runs before uvicorn.run, so the server never starts.

Common situations: Deploying behind a reverse proxy under a sub-path and forgetting the leading slash. Copying a path from a URL bar ('https://host/gpt-academic' instead of '/gpt-academic'). Env-var-driven configs where CUSTOM_PATH comes back as an empty string. Newer revisions where CUSTOM_PATH handling moved, so old .env/config_private.py values no longer validate.

Related errors

AI-assisted analysis of binary-husky/gpt_academic@d6bde0fa54 (2026-08-14). Data as JSON: /api/errors/44fff686a671a894. Report an issue: GitHub.