Graphify-Labs/graphify · error · RuntimeError

could not read Google Workspace shortcut {path}: {exc}

Error message

could not read Google Workspace shortcut {path}: {exc}

What it means

Raised by read_google_shortcut when a .gdoc/.gsheet/.gslides shortcut file cannot be parsed. Google Drive 'shortcut' files are tiny JSON descriptors; graphify reads them to recover the Drive file ID for export. Any failure reading the bytes or decoding them as JSON (missing file handled elsewhere, but malformed JSON, wrong encoding, or an I/O error) is wrapped in a RuntimeError naming the offending path and the underlying exception.

Source

Thrown at graphify/google_workspace.py:68

    for key in ("resource_key", "resourceKey"):
        value = data.get(key)
        if value:
            return str(value)
    if not url:
        return None
    parsed = urllib.parse.urlparse(url)
    query = urllib.parse.parse_qs(parsed.query)
    if query.get("resourcekey"):
        return query["resourcekey"][0]
    return None


def read_google_shortcut(path: Path) -> dict[str, str | None]:
    """Read a .gdoc/.gsheet/.gslides shortcut and return export metadata."""
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except Exception as exc:
        raise RuntimeError(f"could not read Google Workspace shortcut {path}: {exc}") from exc

    url = str(data.get("url") or "")
    file_id = (
        data.get("doc_id")
        or data.get("file_id")
        or data.get("fileId")
        or data.get("id")
        or _extract_file_id_from_url(url)
    )
    if not file_id:
        resource_id = str(data.get("resource_id") or "")
        if ":" in resource_id:
            file_id = resource_id.split(":", 1)[1]

    if not file_id:
        raise RuntimeError(f"Google Workspace shortcut {path} does not include a Drive file ID")

    return {

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. Inspect the file: `cat file.gdoc` — it should be a small JSON object with url/doc_id/file_id keys
2. Re-download or re-create the shortcut from Drive so the JSON payload is intact
3. If the file is not actually a Drive shortcut (wrong extension), exclude or move it so the scanner skips it

Example fix

# before
{"url": "https://docs.google.com/..."   # truncated JSON
graphify build .   # RuntimeError: could not read Google Workspace shortcut

# after — valid shortcut file
{"url": "https://docs.google.com/document/d/<fileId>/edit", "doc_id": "<fileId>"}

import json
from pathlib import Path

def is_readable_shortcut(path: Path) -> bool:
    try:
        json.loads(path.read_text(encoding="utf-8"))
        return True
    except (OSError, json.JSONDecodeError):
        return False

try:
    meta = read_google_shortcut(path)
except RuntimeError as e:
    if "could not read Google Workspace shortcut" in str(e):
        log.warning("skipping corrupt shortcut %s", path)
    else:
        raise

When it happens

Trigger: Ingesting a directory containing Google Workspace shortcuts where path.read_text() or json.loads() throws — truncated file, BOM/encoding damage, a .gdoc that is actually an HTML error page saved by the Drive web UI, or a permissions error reading the file.

Common situations: Downloading Drive files with a tool that renames or rewrites shortcut payloads; symlinking shortcuts from another machine; files synced through channels that corrupt binary-ish content; macOS NFD path surprises are handled separately, so genuine content corruption is the usual cause.

Related errors

• Google Workspace shortcut {path} does not include a Drive fi
• gws is required for Google Workspace export. Install it from
• gws export failed for {file_id}: {stderr}
• Google Sheets export requires the office extra: pip install
• ingest: {exc}

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/0e9c85b66465cfad. Report an issue: GitHub.