jackwener/OpenCLI · error · ArgumentError

Invalid Jira field id in --fields

Error message

Invalid Jira field id in --fields

What it means

ArgumentError from `parseIssueFieldSelection` in clis/jira/shared.js:76, raised when a --fields entry fails the field-id pattern /^[A-Za-z][A-Za-z0-9_.:-]*$/: it must start with a letter and contain only letters, digits, underscore, dot, colon, or hyphen. This catches malformed Jira field ids before a request is sent.

Source

Thrown at clis/jira/shared.js:76

    if (typeof raw !== 'string') {
        throw new ArgumentError('Jira --fields must be a comma-separated string or auto');
    }

    const parts = raw.split(',').map((field) => field.trim());
    if (parts.length === 0 || parts.some((field) => !field)) {
        throw new ArgumentError(
            'Invalid Jira --fields selection',
            'Use comma-separated field ids without empty entries, for example summary,status,customfield_12345.',
        );
    }
    if (parts.some((field) => field.toLowerCase() === 'auto')) {
        if (parts.length !== 1) {
            throw new ArgumentError('Jira --fields auto cannot be combined with other field ids');
        }
        return { mode: 'auto' };
    }
    if (parts.some((field) => !/^[A-Za-z][A-Za-z0-9_.:-]*$/.test(field))) {
        throw new ArgumentError(
            'Invalid Jira field id in --fields',
            'Use Jira field ids such as summary, status, or customfield_12345.',
        );
    }
    return { mode: 'selected', ids: [...new Set(parts)] };
}

function issueFields(extraFields = [], selection = null) {
    if (selection?.mode === 'auto') return '*all';
    if (selection?.mode === 'selected') {
        return [...new Set([...selection.ids, ...extraFields.filter(Boolean)])].join(',');
    }
    const configured = Object.values(configuredFieldNames()).filter(Boolean);
    return [...new Set([...DEFAULT_ISSUE_FIELDS, ...configured, ...extraFields.filter(Boolean)])].join(',');
}

export function issueSelectionIncludes(selection, field) {
    return selection === null || selection?.mode === 'auto' || selection?.ids?.includes(field) === true;

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Use the Jira field id, not the display name: customfield_12345 instead of 'Story Points'.
  2. Look up exact ids via /rest/api/3/field or your Jira admin's field list.
  3. Remove spaces/invalid punctuation; allowed chars: letters, digits, _ . : -
  4. Ensure the entry starts with a letter.

Example fix

// before
--fields="summary,Story Points"
// after
--fields="summary,customfield_10016"
Defensive patterns

Strategy: validation

Validate before calling

const FIELD_ID_RE = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
function assertValidFieldIds(raw) {
  for (const p of String(raw).split(',')) {
    if (p.trim() && !FIELD_ID_RE.test(p.trim())) {
      throw new Error(`--fields entry '${p.trim()}' is not a valid Jira field id`);
    }
  }
  return raw;
}

Type guard

const isFieldId = (s) => typeof s === 'string' && /^[A-Za-z][A-Za-z0-9_.:-]*$/.test(s);

Try / catch

try {
  await run(['jira', 'issue', key, '--fields', fields]);
} catch (e) {
  if (e instanceof ArgumentError && e.message === 'Invalid Jira field id in --fields') {
    console.error('Use ids like summary, status, customfield_12345 (see GET /rest/api/3/field).');
  } else throw e;
}

Prevention

When it happens

Trigger: --fields="summary,status!", entries starting with a digit (e.g. 12345), entries containing spaces, slashes, or CJK characters, or human-readable names like 'Story Points' instead of ids.

Common situations: Using a custom field's NAME instead of its id (customfield_12345); translating keys or adding labels; copy-pasting ids with surrounding quotes, spaces, or unicode punctuation from docs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/95ed7ba33b0d90ce. Report an issue: GitHub.