What causes "One of 'token_path' or 'refresh_token' is required." in docling-project/docling?

Complete the OAuth consent flow once to produce a token file and pass token_path='/path/to/token.json'.

docling-project/docling · error · ValueError

One of 'token_path' or 'refresh_token' is required.

Error message

One of 'token_path' or 'refresh_token' is required.

What it means

GoogleDriveCoordinates runs a model validator requiring an OAuth token for Google Drive access: either token_path (a serialized-token file path) or refresh_token must be provided. Without one of these the coordinates cannot authenticate to Google Drive, so the model refuses to construct.

Source

Thrown at docling/datamodel/service/sources.py:385

            ),
            examples=[
                "./dev/google_drive_credentials.json",
            ],
        ),
    ]

    credentials: Annotated[
        Optional[GoogleDriveCredentials],
        Field(
            default=None,
            description="OAuth 2.0 Client ID' credentials (available in Google Cloud console). One of 'credentials_path' or 'credentials' is required.",
        ),
    ]

    @model_validator(mode="after")
    def validate_auth_inputs(self) -> "GoogleDriveCoordinates":
        if not (self.token_path or self.refresh_token):
            raise ValueError("One of 'token_path' or 'refresh_token' is required.")
        if not (self.credentials_path or self.credentials):
            raise ValueError("One of 'credentials_path' or 'credentials' is required.")
        return self

View on GitHub (pinned to 61d76f1ff3)

Solutions

Complete the OAuth consent flow once to produce a token file and pass token_path='/path/to/token.json'.
Alternatively pass refresh_token directly if you manage tokens yourself (e.g. from a secret store).
In containers, mount or inject the token file/secret so token_path or refresh_token is always set.

Example fix

# before
src = GoogleDriveCoordinates(
    file_id="abc123",
    credentials_path="credentials.json",
)

# after
src = GoogleDriveCoordinates(
    file_id="abc123",
    credentials_path="credentials.json",
    token_path="token.json",
)

Defensive patterns

Strategy: validation

Validate before calling

def has_gdrive_token(cfg: dict) -> bool:
    return bool(cfg.get("token_path") or cfg.get("refresh_token"))

assert has_gdrive_token(cfg), "Google Drive source needs token_path or refresh_token"

Type guard

def gdrive_auth_complete(cfg: dict) -> bool:
    return bool(cfg.get("token_path") or cfg.get("refresh_token"))

Try / catch

try:
    src = GoogleDriveCoordinates(**cfg)
except ValidationError as e:
    if "token_path" in str(e):
        run_oauth_consent_flow()  # produce token.json, then retry
    else:
        raise

Prevention

Persist the OAuth token file next to credentials and mount both in containers.
Add startup checks that required Google Drive secrets exist before serving traffic.

When it happens

Trigger: Building a Google Drive source with only coordinates/credentials, e.g. GoogleDriveCoordinates(credentials_path='creds.json') with neither token_path nor refresh_token; the validator validate_auth_inputs raises before any network call.

Common situations: First-time Google Drive setup where the developer configured the OAuth client (credentials_path) but never completed the consent flow to obtain a token; environment differences where the token file path exists on the dev machine but not in the container; copy-pasting examples that omit the token fields.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/2c3711ff9d06fbd6. Report an issue: GitHub.