reflex-dev/reflex · error · SystemExit

Cannot use --single-port with --frontend-only or --backend-o

Error message

Cannot use --single-port with --frontend-only or --backend-only.

What it means

Reflex's CLI refuses to start when --single-port is combined with --frontend-only or --backend-only. Single-port mode serves the frontend and backend from one process/port, so running only one side of the app is contradictory. The check lives in reflex.reflex.run before any server is started.

Source

Thrown at reflex/reflex.py:537

    backend_host: str | None,
    single_port: bool,
):
    """Run the app in the current directory."""
    from reflex.utils import prerequisites

    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)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Remove --frontend-only/--backend-only from the command when using --single-port
2. If you truly need only one side, drop --single-port and use the dedicated flags alone
3. Check shell scripts/CI YAML for flag accumulation (e.g. EXTRA_FLAGS env var) that adds these flags implicitly

Example fix

# before
reflex run --single-port --frontend-only

# after
reflex run --single-port

import sys
single = '--single-port' in sys.argv or '-s' in sys.argv
side = '--frontend-only' in sys.argv or '-f' in sys.argv or '--backend-only' in sys.argv or '-b' in sys.argv
if single and side:
    sys.exit('single-port cannot be combined with frontend-only/backend-only')

When it happens

Trigger: Running `reflex run --single-port --frontend-only` or `reflex run --single-port --backend-only` (or the short flags -s with -f/-b).

Common situations: Copy-pasting run flags from different docs/tutorials; scripts that layer flags via environment or config and accidentally enable both modes; CI pipelines reusing a run command after switching to single-port deployment.

Related errors

• Cannot specify different ports for frontend and backend when
• Only one of `data` or `fp` may be provided, not both.
• At least one of `data` or `fp` must be provided.
• Could not find module {config.module}.
• Only {template_name=} should be provided, got {template_code

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