PaddlePaddle/PaddleOCR · error · ValueError

source_ref must be a non-empty ref without whitespace

Error message

source_ref must be a non-empty ref without whitespace

What it means

tools/resolve_doc_github_refs.py is a docs-release helper that rewrites a placeholder string across all .md/.yml/.yaml files under a root. Before touching anything it validates source_ref: it must be non-empty, must not have leading/trailing whitespace, and must contain no whitespace anywhere. This ValueError prevents substituting malformed refs (e.g. 'main ' or 'release 2.9') into hundreds of documentation files, which would be tedious to revert.

Source

Thrown at tools/resolve_doc_github_refs.py:15

#!/usr/bin/env python3
import argparse
from pathlib import Path


TEXT_SUFFIXES = {".md", ".yml", ".yaml"}


def resolve_placeholders(root, placeholder, source_ref):
    if (
        not source_ref
        or source_ref.strip() != source_ref
        or any(c.isspace() for c in source_ref)
    ):
        raise ValueError("source_ref must be a non-empty ref without whitespace")

    root = Path(root)
    changed = []
    for path in sorted(root.rglob("*")):
        if not path.is_file() or path.suffix not in TEXT_SUFFIXES:
            continue
        content = path.read_text(encoding="utf-8")
        if placeholder not in content:
            continue
        path.write_text(content.replace(placeholder, source_ref), encoding="utf-8")
        changed.append(path)
    return changed


def main(argv=None):
    parser = argparse.ArgumentParser(
        description="Resolve docs GitHub source-ref placeholders before building docs."
    )

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Pass a clean single token: --source-ref v2.9.0 or --source-ref main
2. Quote the shell variable and strip it first: --source-ref "${REF// /}" or REF=$(echo "$REF" | tr -d '[:space:]')
3. Validate in CI before invoking: [ -n "$REF" ] && [[ "$REF" != *[' ']* ]] || exit 1

Example fix

# before
python tools/resolve_doc_github_refs.py --root docs --placeholder '@REF@' --source-ref "main "

# after
python tools/resolve_doc_github_refs.py --root docs --placeholder '@REF@' --source-ref main

assert source_ref and source_ref == source_ref.strip() and not any(c.isspace() for c in source_ref), \
    f'source_ref must be a single token without whitespace, got {source_ref!r}'

def is_clean_ref(ref: str) -> bool:
    return bool(ref) and ref.strip() == ref and not any(c.isspace() for c in ref)

try:
    resolve_placeholders(root, placeholder, source_ref)
except ValueError as e:
    if 'source_ref' in str(e):
        raise SystemExit(f'invalid --source-ref {source_ref!r}: pass a single git ref like v2.9.0')
    raise

When it happens

Trigger: Running the script with --source-ref containing a space, tab, newline, or surrounding whitespace: python tools/resolve_doc_github_refs.py --source-ref 'main ' or '--source-ref v2.9 rc'.

Common situations: Shell quoting accidents letting extra words into the argument; copy-pasting a ref with a trailing newline; CI passing an unset/whitespace variable as the ref.

Related errors

• fileUrl and filePath are mutually exclusive.
• File not found: ${path}
• Bad request: ${text}
• OCR pipeline config text must decode to an object.
• OCR pipeline config must be an object or YAML text.

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