jackwener/OpenCLI · error · ArgumentError

tvmaze show id is required and must be a positive integer

Error message

tvmaze show id is required and must be a positive integer

What it means

requireShowId validates that the `id` argument is a positive integer before any HTTP request is made, throwing ArgumentError with a hint pointing to how TVmaze show ids appear in URLs. It accepts numbers or numeric strings but rejects anything else — floats, zero, negatives, non-numeric strings, empty values. This fails fast to avoid pointless API calls to /shows/<invalid>.

Source

Thrown at clis/tvmaze/utils.js:20

//
// TVmaze publishes a free, unauthenticated REST API at https://api.tvmaze.com.
// Docs: https://www.tvmaze.com/api
import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const TVMAZE_BASE = 'https://api.tvmaze.com';
const UA = 'opencli-tvmaze-adapter (+https://github.com/jackwener/opencli)';

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`tvmaze ${label} cannot be empty`);
    return s;
}

export function requireShowId(value) {
    const raw = value;
    const n = typeof raw === 'number' ? raw : Number(String(raw ?? '').trim());
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(
            'tvmaze show id is required and must be a positive integer',
            'TVmaze show ids appear in the URL: https://www.tvmaze.com/shows/<id>/<slug>.',
        );
    }
    return n;
}

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`tvmaze ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`tvmaze ${label} must be <= ${maxValue}`);
    }
    return n;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Extract the numeric segment from the TVmaze URL: https://www.tvmaze.com/shows/<id>/<slug> — use <id>, not the slug.
2. If you only know the show name, run `tvmaze search` first and use the returned show.id.
3. Cast numeric strings carefully; ensure the value is a whole number > 0 before calling.
4. Catch ArgumentError and display the hint about the URL format to end users.

Example fix

// before
await tvmazeShow('game-of-thrones'); // slug, not id
// after
await tvmazeShow(82); // numeric id from tvmaze.com/shows/82/game-of-thrones

function toShowId(v) {
    const n = typeof v === 'number' ? v : Number(String(v ?? '').trim());
    if (!Number.isInteger(n) || n <= 0) {
        throw new Error(`invalid TVmaze show id: ${JSON.stringify(v)}`);
    }
    return n;
}

function isValidShowId(v) {
    const n = typeof v === 'number' ? v : Number(String(v ?? '').trim());
    return Number.isInteger(n) && n > 0;
}

try {
    const show = await tvmazeShow(idArg);
} catch (err) {
    if (err instanceof ArgumentError && err.message.includes('positive integer')) {
        console.error('Pass the numeric id from https://www.tvmaze.com/shows/<id>/<slug>');
        process.exitCode = 2;
    } else {
        throw err;
    }
}

When it happens

Trigger: Calling `tvmaze show` with an id like 'abc', '12.5', '0', '-3', '' , or undefined — e.g. copying the show slug ('game-of-thrones') instead of the numeric id from a TVmaze URL, or passing a name where an id is expected.

Common situations: Extracting the wrong URL segment (slug vs id) from a TVmaze link; passing a show name string; spreadsheet/copy errors losing digits; scripts interpolating undefined variables into the id position.

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

• tvmaze ${label} cannot be empty
• archive search sort must be one of ${SORT_OPTIONS.join(', ')
• archive search mediatype must be one of ${MEDIATYPES.join(',
• archive search limit must be a positive integer
• archive search query must not be empty

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