jackwener/OpenCLI · error · ArgumentError

Jira --fields must be a comma-separated string or auto

Error message

Jira --fields must be a comma-separated string or auto

What it means

ArgumentError from `parseIssueFieldSelection` in clis/jira/shared.js:59, raised when the --fields value is defined but not a string. The parser only accepts undefined (no selection), a comma-separated string of field ids, or the literal 'auto'. Any other type (number, boolean, object) is rejected before any Jira request is made.

Source

Thrown at clis/jira/shared.js:59

    return `${jiraApiPrefix(config)}${resource.startsWith('/') ? resource : `/${resource}`}${params ? queryString(params) : ''}`;
}

export async function jiraRequest(config, resource, options = {}) {
    return atlassianRequest(config, jiraApiPath(config, resource, options.params), options);
}

function configuredFieldNames() {
    return {
        acceptanceCriteria: process.env.ATLASSIAN_JIRA_ACCEPTANCE_FIELD?.trim() || '',
        sprint: process.env.ATLASSIAN_JIRA_SPRINT_FIELD?.trim() || '',
        storyPoints: process.env.ATLASSIAN_JIRA_STORY_POINTS_FIELD?.trim() || '',
    };
}

export function parseIssueFieldSelection(raw) {
    if (raw === undefined) return null;
    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',

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Quote the value: --fields="summary,status" so the shell/CLI receives a string.
  2. In calling code, coerce first: String(raw) before invoking, or pass undefined to use the default field set.
  3. If passing config programmatically, ensure the option value is typeof 'string'.

Example fix

// before
fields: config.issueFields // 123 (number)
// after
fields: config.issueFields == null ? undefined : String(config.issueFields)
Defensive patterns

Strategy: validation

Validate before calling

function assertFieldsString(raw) {
  if (raw !== undefined && typeof raw !== 'string') {
    throw new TypeError('--fields must be a string like "summary,status" or "auto"');
  }
  return raw;
}

Type guard

const isFieldsValue = (v) => v === undefined || typeof v === 'string';

Try / catch

import { ArgumentError } from '@jackwener/opencli/errors';
try {
  await run(['jira', 'issue', key, '--fields', fields]);
} catch (e) {
  if (e instanceof ArgumentError && e.message.includes('--fields must be')) {
    console.error('Quote the value: --fields="summary,status"');
  } else throw e;
}

Prevention

When it happens

Trigger: Passing --fields with a non-string value, e.g. --fields=123 (numeric), programmatic invocation passing a number/boolean/array instead of a string into the `selection` option.

Common situations: Wrapping the jira CLI in a script that passes parsed YAML/JSON config values straight through; shell quoting stripping quotes so numbers arrive unquoted; templating that interpolates objects.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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