PaddlePaddle/PaddleOCR · error · RuntimeError

Environment Variable CUDA_VISIBLE_DEVICES is not set correct

Error message

Environment Variable CUDA_VISIBLE_DEVICES is not set correctly. If you wanna use gpu, please set CUDA_VISIBLE_DEVICES via export CUDA_VISIBLE_DEVICES=cuda_device_id.

What it means

Raised by the PaddleHub kie_ser module when initializing with use_gpu=True and the CUDA_VISIBLE_DEVICES environment variable is missing, empty, or its first character is not a digit. The check is a bare try/except around os.environ["CUDA_VISIBLE_DEVICES"] plus int(_places[0]), so a KeyError (unset) and a ValueError (e.g. "", "all", "NoDevFiles") both land in the same generic message. It is a deployment-configuration error, not a code bug.

Source

Thrown at deploy/hubserving/kie_ser/module.py:64

    type="cv/KIE_SER",
)
class KIESer(hub.Module):
    def _initialize(self, use_gpu=False, enable_mkldnn=False):
        """
        initialize with the necessary elements
        """
        cfg = self.merge_configs()

        cfg.use_gpu = use_gpu
        if use_gpu:
            try:
                _places = os.environ["CUDA_VISIBLE_DEVICES"]
                int(_places[0])
                print("use gpu: ", use_gpu)
                print("CUDA_VISIBLE_DEVICES: ", _places)
                cfg.gpu_mem = 8000
            except:
                raise RuntimeError(
                    "Environment Variable CUDA_VISIBLE_DEVICES is not set correctly. If you wanna use gpu, please set CUDA_VISIBLE_DEVICES via export CUDA_VISIBLE_DEVICES=cuda_device_id."
                )
        cfg.ir_optim = True
        cfg.enable_mkldnn = enable_mkldnn

        self.ser_predictor = SerPredictor(cfg)

    def merge_configs(
        self,
    ):
        # default cfg
        backup_argv = copy.deepcopy(sys.argv)
        sys.argv = sys.argv[:1]
        cfg = parse_args()

        update_cfg_map = vars(read_params())

        for key in update_cfg_map:

View on GitHub (pinned to 2661c7c0ef)

Solutions

Export the variable before starting the service: export CUDA_VISIBLE_DEVICES=0 (single GPU) and restart
Pass it into the container/pod: docker run -e CUDA_VISIBLE_DEVICES=0 ... / env in the pod spec
If no GPU is intended, start the module with use_gpu=False instead
Ensure the value starts with a digit ("0", "0,1"); avoid "", "all", or "-1"

Example fix

# before
cuda: docker run -p 8866:8866 kie_ser_ser:latest  # env missing -> RuntimeError

# after
docker run -p 8866:8866 -e CUDA_VISIBLE_DEVICES=0 --gpus all kie_ser_ser:latest

Defensive patterns

Strategy: validation

Validate before calling

import os

def gpu_env_ok() -> bool:
    v = os.environ.get("CUDA_VISIBLE_DEVICES", "")
    return len(v) > 0 and v[0].isdigit()

assert gpu_env_ok() or not USE_GPU, "set CUDA_VISIBLE_DEVICES=0 before GPU serving"

Try / catch

try:
    module = SerPredictorModule(use_gpu=True)
except RuntimeError as e:
    if "CUDA_VISIBLE_DEVICES" in str(e):
        os.environ["CUDA_VISIBLE_DEVICES"] = "0"
        module = SerPredictorModule(use_gpu=True)
    else:
        raise

Prevention

Set CUDA_VISIBLE_DEVICES=0 in the service unit/entrypoint script
Pass env explicitly in docker run / pod specs
Never use "", "all", or "-1" with these hub modules
Add a startup preflight check for the env var when use_gpu is true

When it happens

Trigger: Starting hubserving with use_gpu=True without exporting CUDA_VISIBLE_DEVICES; setting it to "" or "all" (int('a') fails); docker/k8s containers where the variable was not passed through; set to a value like "1,2" works, but "-1" fails because int('-') raises.

Common situations: GPU serving in Docker without -e CUDA_VISIBLE_DEVICES=0; Kubernetes pods missing the env entry; following CPU-oriented quickstart docs then flipping use_gpu; variable set to "all" on newer drivers.

Related errors

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/86b16eb6f78e5962. Report an issue: GitHub.