abhigyanpatwari/GitNexus · error · Error

[understand-quickly] expected id of the form "owner/repo", g

Error message

[understand-quickly] expected id of the form "owner/repo", got "${id}". The registry uses this string to look up your entry in registry.json — it must match the GitHub owner/repo of the source code, not a local path.

What it means

Thrown by buildUqDispatchPayload() when the `id` argument does not match the `owner/repo` shape required by the understand-quickly registry. The validator (isValidOwnerRepo) enforces GitHub slug rules: one slash, no whitespace, owner starts/ends alphanumeric (max 39 chars), repo is alnum/dot/hyphen/underscore (max 100 chars). This fails loudly before the network round-trip so a misconfigured caller doesn't get a confusing 422 from GitHub.

Source

Thrown at gitnexus-shared/src/integrations/understand-quickly.ts:51

export const UNDERSTAND_QUICKLY_TOKEN_ENV = 'UNDERSTAND_QUICKLY_TOKEN';

export interface UqDispatchPayload {
  event_type: typeof UNDERSTAND_QUICKLY_EVENT_TYPE;
  client_payload: {
    /** `<owner>/<repo>` shape — must match the registered entry. */
    id: string;
  };
}

/**
 * Build the JSON body for the `repository_dispatch` ping. Pure — no
 * env reads, no network. Validates that `id` looks like `owner/repo`
 * (one slash, no whitespace, both halves non-empty) so a misconfigured
 * caller fails loudly before the round-trip.
 */
export function buildUqDispatchPayload(id: string): UqDispatchPayload {
  if (!isValidOwnerRepo(id)) {
    throw new Error(
      `[understand-quickly] expected id of the form "owner/repo", got "${id}". ` +
        `The registry uses this string to look up your entry in registry.json — ` +
        `it must match the GitHub owner/repo of the source code, not a local path.`,
    );
  }
  return {
    event_type: UNDERSTAND_QUICKLY_EVENT_TYPE,
    client_payload: { id },
  };
}

/**
 * `owner/repo` validation. Conservative on purpose: GitHub's actual
 * naming rules are looser, but we want to catch local paths
 * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
 *
 * Matches GitHub's published slug rules:
 *   owner: starts with alnum, then alnum/hyphen only, must end with

View on GitHub (pinned to d540b00184)

Solutions

1. Pass the literal 'owner/repo' slug matching the registered entry in registry.json
2. If deriving from a git remote, use parseOwnerRepoFromRemote() which strips .git and trailing slashes and extracts owner/repo
3. Validate with isValidOwnerRepo(id) before calling buildUqDispatchPayload to surface the problem at the right layer
4. Check for stray whitespace, multiple slashes, or a leading/trailing hyphen in the owner half

Example fix

// before — passing a local path
buildUqDispatchPayload('/Users/me/code/my-repo'); // throws

// after — pass the GitHub owner/repo slug
buildUqDispatchPayload('my-org/my-repo');

// or derive it from the git remote
const id = parseOwnerRepoFromRemote('git@github.com:my-org/my-repo.git');
if (id) buildUqDispatchPayload(id);

import { isValidOwnerRepo } from 'gitnexus-shared/src/integrations/understand-quickly.js';
// Validate before constructing the payload
if (!isValidOwnerRepo(id)) {
  throw new Error(`Refusing to build dispatch payload: '${id}' is not owner/repo`);
}
const payload = buildUqDispatchPayload(id);

import { isValidOwnerRepo } from 'gitnexus-shared/src/integrations/understand-quickly.js';
function isOwnerRepo(s: string): s is string { return isValidOwnerRepo(s); } // nominal; the value is already a string

try {
  const payload = buildUqDispatchPayload(id);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('[understand-quickly]')) {
    // surface a clear config error to the user; suggest deriving from git remote
    const derived = parseOwnerRepoFromRemote(gitRemoteUrl);
    if (derived) return buildUqDispatchPayload(derived);
  }
  throw e;
}

When it happens

Trigger: Calling buildUqDispatchPayload(id) where id is a local filesystem path (/Users/x/repo), a bare slug (my-repo), contains whitespace, has multiple slashes, uses an underscore/dot in the owner segment, or has a trailing hyphen in the owner. Any of these fail the regex /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9._-]{1,100}$/.

Common situations: Passing an absolute local path instead of the GitHub owner/repo; copy-pasting a git remote URL (git@github.com:owner/repo.git) instead of the slug; trailing slash or .git suffix not stripped; a typo introducing a space; an organization name with a trailing hyphen that GitHub itself rejects at creation.

Related errors

• benchmark index metadata is malformed: {metadata_path}
• benchmark index metadata must be an object: {metadata_path}
• benchmark index metadata is missing indexedAt or lastCommit
• Unsupported provider: ${(config as any).provider}
• Invalid backend URL: must be a well-formed http:// or https:

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/f48fb4def00f31ba. Report an issue: GitHub.