reflex-dev/reflex · error · SystemExit

Cannot specify different ports for frontend and backend when

Error message

Cannot specify different ports for frontend and backend when using --single-port.

What it means

In single-port mode Reflex serves frontend and backend over one port, so explicitly requesting two different ports is rejected. The check fires only when both --frontend-port and --backend-port are given and their values differ. It runs early in reflex.reflex.run before configuration is applied.

Source

Thrown at reflex/reflex.py:542

    if frontend_only and backend_only:
        logger.error("Cannot use both --frontend-only and --backend-only options.")
        raise SystemExit(1)

    if single_port:
        if env != constants.Env.PROD:
            logger.error("--single-port can only be used with --env=PROD.")
            raise SystemExit(1)
        if frontend_only or backend_only:
            logger.error(
                "Cannot use --single-port with --frontend-only or --backend-only."
            )
            raise SystemExit(1)
        if frontend_port and backend_port and frontend_port != backend_port:
            logger.error(
                "Cannot specify different ports for frontend and backend when using --single-port."
            )
            raise SystemExit(1)

    config = get_config()

    frontend_port = frontend_port or config.frontend_port
    backend_port = backend_port or config.backend_port
    backend_host = backend_host or config.backend_host

    environment.REFLEX_COMPILE_CONTEXT.set(constants.CompileContext.RUN)
    environment.REFLEX_BACKEND_ONLY.set(backend_only)
    environment.REFLEX_FRONTEND_ONLY.set(frontend_only)

    running_mode = prerequisites.check_running_mode(frontend_only, backend_only)

    _run(
        env=constants.Env(env),
        running_mode=running_mode,
        frontend_port=frontend_port,
        backend_port=backend_port,

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Pass the same port to both flags, e.g. --frontend-port 8000 --backend-port 8000
2. Or omit both port flags in single-port mode and let Reflex use the configured/default single port
3. Set frontend_port = backend_port in rxconfig.py if ports are configured in the file

Example fix

# before
reflex run --single-port --frontend-port 3000 --backend-port 8000

# after
reflex run --single-port --frontend-port 8000 --backend-port 8000

import sys
argv = sys.argv
if '--single-port' in argv or '-s' in argv:
    fp = next((argv[i+1] for i, a in enumerate(argv) if a in ('--frontend-port',) and i+1 < len(argv)), None)
    bp = next((argv[i+1] for i, a in enumerate(argv) if a in ('--backend-port',) and i+1 < len(argv)), None)
    if fp and bp and fp != bp:
        sys.exit('ports must match in single-port mode')

When it happens

Trigger: `reflex run --single-port --frontend-port 3000 --backend-port 8000` (ports differ), or rxconfig.py values combined with one CLI port flag that conflicts.

Common situations: Existing projects already configured with separate frontend/backend ports (default 3000/8000) being migrated to single-port mode; copied config with explicit ports while adopting --single-port.

Related errors

• Cannot use --single-port with --frontend-only or --backend-o
• Could not find module {config.module}.
• Failed to download the template: {he}
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/107cafc8e7ffe255. Report an issue: GitHub.