docling-project/docling · error · ValueError

One of 'credentials_path' or 'credentials' is required.

Error message

One of 'credentials_path' or 'credentials' is required.

What it means

The same GoogleDriveCoordinates validator requires OAuth 2.0 client credentials: either credentials_path (a file path) or an inline credentials object (GoogleDriveCredentials) must be provided. The client credentials identify the Google Cloud OAuth app; without them the refresh-token flow cannot run, so the model fails validation.

Source

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

                "./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

1. Download the OAuth client credentials JSON from Google Cloud console and pass credentials_path='client_credentials.json'.
2. Or embed them inline via credentials=GoogleDriveCredentials(...) (e.g. client_id/client_secret from a secret manager).
3. Ensure the credentials pair belongs to the same OAuth app that issued your refresh_token.

Example fix

# before
src = GoogleDriveCoordinates(
    file_id="abc123",
    refresh_token="1//0abc...",
)

# after
src = GoogleDriveCoordinates(
    file_id="abc123",
    refresh_token="1//0abc...",
    credentials_path="client_credentials.json",
)

def has_gdrive_credentials(cfg: dict) -> bool:
    return bool(cfg.get("credentials_path") or cfg.get("credentials"))

assert has_gdrive_credentials(cfg), "Google Drive source needs credentials_path or credentials"

def gdrive_credentials_complete(cfg: dict) -> bool:
    return bool(cfg.get("credentials_path") or cfg.get("credentials"))

try:
    src = GoogleDriveCoordinates(**cfg)
except ValidationError as e:
    if "credentials_path" in str(e):
        raise ConfigError("Missing OAuth client credentials for Google Drive") from e
    raise

When it happens

Trigger: Constructing GoogleDriveCoordinates with refresh_token='...' but no credentials_path and no credentials object; any combination missing both credential sources raises from validate_auth_inputs.

Common situations: Passing only a refresh token harvested from another tool without supplying the client_id/client_secret it belongs to; secrets stored per-environment and the credentials file not mounted in the new environment; renaming the field from an older docling release where credentials were configured globally.

Related errors

• One of 'token_path' or 'refresh_token' is required.
• Cannot convert Box Note with hash {self.document_hash}: no '
• Cannot convert doc with {self.document_hash} because the bac
• Archive exceeds maximum member count limit of {self.options.
• Invalid base_path format: '{base_path}'

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