Skip to content

Validate data source keys at config load instead of sending an absent key to Figma #706

Description

@nathanacurtis

Problem

A source with no key: value in the workspace settings is not caught anywhere. fetch builds the request URL from the missing value and sends the literal string undefined as the file key. Figma answers 404, and the CLI reports it as a key that is stale or out of reach — so the message names a cause that isn't the cause, and points at a key that was never there.

The same gap has a second consequence: a full Figma file URL pasted into a config key also 404s, while --source <url> accepts one and resolves it to a key.

Observed:

[CLI] GET file: https://api.figma.com/v1/files/undefined?geometry=paths
Error: File not found (404) while fetching organisms.file
  Figma returned 404 for the file key configured for "organisms".
  This usually means the key in your config is stale or out of reach:
    • The file was moved, deleted, or recreated (keys change on duplicate/recreate)
    • Your FIGMA_TOKEN account cannot open this file

Potential solution(s)

  • Fail at config load, naming the source and the missing field, before any network call is made
  • Accept a Figma file URL in a config key the same way --source does

Acceptance criteria

  • A source with an empty or missing key fails before any request is sent, naming the source and the field
  • The failure message never suggests the key is stale or out of reach
  • A full Figma file URL in a config key resolves to the file key, as --source does
  • No request is ever sent with undefined as the file key

Case data

  • Workspace: fm — during a fetch
  • Territory: cli
  • Impacted file(s): packages/cli/src/commands/FetchCommand.ts (normalizeSources), packages/cli/src/Config/ConfigLoader.ts, packages/cli/src/utilities/figmaFileKey.ts
  • Size: s

Notes

Found while diagnosing two unrelated specs fetch failures in one run. The other failure in that run was an intermittent transport drop on a large file payload, tracked separately.


Implementation details are tracked internally.

Activity

  1. self-assigned this
    on Oct 7, 2026
  2. added theissue type on Oct 7, 2026
  3. nathanacurtis commented on Oct 8, 2026

    @nathanacurtis
    MemberAuthor

    Fixed on fix/fetch-error-accuracy (PR #710).

    A source whose key is missing, empty, or unusable now fails before any request, naming the source and the field:

    Error: A configured source cannot address a Figma file.
      data.sources.nokey.key — no key is set (found: (empty))
      Set each to a file key, or paste the file's Figma URL and it will be read from that.
      Check: the workspace settings (config/settings.yaml)
    

    Every acceptance criterion verified against the real API:

    • Fails before any request is sent, naming the source and the field — exit 2
    • No mention of stale, moved, or out of reach
    • A full Figma file URL in a config key resolves to the file key, as --source does (a branch URL resolves to the branch)
    • Nothing is ever sent with undefined as the file key

    Every unusable key in a settings file is reported in one run rather than failing at the first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

clispecs-cli commands

Type

Fields

Priority

None yet

Projects

  • Status
    Ready to release

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions