What causes "Invalid limit: ${value}" in affaan-m/ECC?

Omit the limit argument entirely (or pass undefined/null) to use the function's fallback instead of passing 0.

Invalid limit: ${value}

Error message

Invalid limit: ${value}

What it means

Thrown by normalizeLimit() in the state-store queries module when a caller-supplied limit value, after Number.parseInt(_, 10), is not a finite positive integer. The function exists to clamp query sizes for list-style DB queries (sessions, runs, decisions), so a zero, negative, NaN, or non-finite value would either return no rows or be passed straight to SQL where it could cause downstream errors.

Source

Thrown at scripts/lib/state-store/queries.js:18

'use strict';

const { assertValidEntity } = require('./schema');

const ACTIVE_SESSION_STATES = ['active', 'running', 'idle'];
const SUCCESS_OUTCOMES = new Set(['success', 'succeeded', 'passed']);
const FAILURE_OUTCOMES = new Set(['failure', 'failed', 'error']);
const CLOSED_WORK_ITEM_STATUSES = new Set(['done', 'closed', 'resolved', 'merged', 'cancelled']);
const ATTENTION_WORK_ITEM_STATUSES = new Set(['blocked', 'needs-review', 'failed', 'stalled']);

function normalizeLimit(value, fallback) {
  if (value === undefined || value === null) {
    return fallback;
  }

  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    throw new Error(`Invalid limit: ${value}`);
  }

  return parsed;
}

function parseJsonColumn(value, fallback) {
  if (value === null || value === undefined || value === '') {
    return fallback;
  }

  return JSON.parse(value);
}

function stringifyJson(value, label) {
  try {
    return JSON.stringify(value);
  } catch (error) {
    throw new Error(`Failed to serialize ${label}: ${error.message}`);

View on GitHub (pinned to 01e15490f0)

Solutions

Omit the limit argument entirely (or pass undefined/null) to use the function's fallback instead of passing 0.
Coerce user input upstream: const limit = Number(input); if (!Number.isInteger(limit) || limit < 1) limit = DEFAULT_PAGE_SIZE;
Treat 0 or negative values as 'use default' in your wrapper instead of forwarding them.
Validate env-derived limits with /^[1-9][0-9]*$/ before parsing.

Example fix

// before
listSessions({ limit: 0 });   // -> Invalid limit: 0

// after
function safeLimit(raw, fallback = 50) {
  const n = Number.parseInt(raw, 10);
  return Number.isFinite(n) && n > 0 ? n : fallback;
}
listSessions({ limit: safeLimit(input.limit) });

Defensive patterns

Strategy: validation

Validate before calling

function safeLimit(raw, fallback = 50) {
  if (raw === undefined || raw === null) return fallback;
  const n = Number.parseInt(raw, 10);
  return Number.isFinite(n) && n > 0 ? n : fallback;
}

listSessions({ limit: safeLimit(input.limit) });

Type guard

function isPositiveLimit(value) {
  if (value === undefined || value === null) return true;  // falls back
  const n = Number.parseInt(value, 10);
  return Number.isFinite(n) && n > 0;
}

Try / catch

try {
  listSessions({ limit });
} catch (error) {
  if (/Invalid limit/.test(error.message)) {
    listSessions({});  // use the library default
    return;
  }
  throw error;
}

Prevention

Pass undefined (not 0) when you want the default — undefined/null are accepted, 0 is not.
Wrap user input in safeLimit at every ingress point.
Document 'omit for default' rather than '0 for default' in your own CLI help.
Validate env-derived limits with a regex before parsing.

When it happens

Trigger: Calling a query helper with limit: 0, limit: -5, limit: 'abc', limit: NaN, limit: Infinity (Number.isFinite rejects it), limit: 2.5 (parseInt floors to 2 but a downstream guard could still complain in other variants), or limit: '' (parseInt returns NaN).

Common situations: CLI --limit flag left empty by the user; reading the value from an env var that is unset (undefined is allowed and falls back, but an empty string is not); config file with limit: 0 meaning 'no limit' that the caller expected to be a sentinel; JSON payload coercion turning null into 0.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/e89de0f785b3259f. Report an issue: GitHub.