Graphify-Labs/graphify · error · RuntimeError

Google Workspace shortcut {path} does not include a Drive fi

Error message

Google Workspace shortcut {path} does not include a Drive file ID

What it means

Raised by read_google_shortcut when the shortcut JSON parsed fine but no Drive file ID could be recovered. The exporter tries doc_id, file_id, fileId, id, then parses the url query/path, then tries resource_id with a 'prefix:id' split; if all of those are empty, there is nothing to export and it raises instead of calling gws with a blank ID.

Source

Thrown at graphify/google_workspace.py:84

        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 {
        "file_id": str(file_id),
        "url": url or None,
        "resource_key": _extract_resource_key(url, data),
        "account": str(data.get("email")) if data.get("email") else None,
    }


def _run_gws_export(file_id: str, mime_type: str, output: Path, resource_key: str | None = None) -> None:
    exe = shutil.which("gws")
    if not exe:
        raise RuntimeError(
            "gws is required for Google Workspace export. Install it from "
            "https://github.com/googleworkspace/cli and run `gws auth login -s drive`."
        )

    params: dict[str, str] = {"fileId": file_id, "mimeType": mime_type}

View on GitHub (pinned to 7fe58b0b0f)

Solutions

1. Open the shortcut JSON and add a recognized key: "doc_id" or "file_id" with the Drive file ID
2. Or set url to a standard Drive URL containing the ID (https://docs.google.com/.../d/<fileId>/...)
3. If the target is a Drive folder or non-exportable item, remove the shortcut from the scanned tree

Example fix

# before
{"url": "https://drive.google.com/", "name": "spec"}   # no ID anywhere

# after
{"url": "https://docs.google.com/document/d/1AbC.../edit", "doc_id": "1AbC..."}

import re

SHORTCUT_KEYS = ("doc_id", "file_id", "fileId", "id")
_DRIVE_ID_RE = re.compile(r"/d/([A-Za-z0-9_-]{10,})")

def shortcut_has_file_id(data: dict) -> bool:
    if any(data.get(k) for k in SHORTCUT_KEYS):
        return True
    url = str(data.get("url") or "")
    if _DRIVE_ID_RE.search(url):
        return True
    rid = str(data.get("resource_id") or "")
    return ":" in rid and rid.split(":", 1)[1] != ""

try:
    meta = read_google_shortcut(path)
except RuntimeError as e:
    if "does not include a Drive file ID" in str(e):
        log.warning("shortcut %s lacks a file ID - skipping", path)
    else:
        raise

When it happens

Trigger: A .gdoc/.gsheet/.gslides file whose JSON has none of the recognized ID keys, a url without an extractable ID (e.g. a folder link or FQDN-only url), and no colon-separated resource_id — e.g. hand-written shortcuts or a schema change by whatever produced the file.

Common situations: Team-created shortcut files with custom/internal key names; Drive schema drift in third-party sync tools; shortcuts to Drive folders (no document file ID) saved with document extensions.

Related errors

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

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