chatboxai/chatbox · warning · ChatboxCliUsageError

Missing session id.

Error message

Missing session id.

What it means

ChatboxCliUsageError thrown by the 'chats read' command when parsed.positionals[0] is falsy (undefined or empty). It is a usage error returned as { ok:false, kind:'usage' } by the CLI executor; the command requires exactly one session-id positional before it touches the store.

Source

Thrown at src/renderer/packages/chatbox-cli/chats.ts:102

            if (!isReadableConversationMessage(message)) continue
            hits.push({
              sessionId: session.id,
              sessionName: session.name,
              ...compactMessage(message),
            })
          }
        }
      })
      return { scope: 'global', query, hits, limitReached: hits.length >= limit }
    },
  },
  {
    path: ['chats', 'read'],
    description: 'Read compact user/assistant messages from one conversation without approval.',
    usage: 'chatbox chats read <session-id> [--limit 20] [--cursor 0]',
    async execute({ parsed }) {
      const sessionId = parsed.positionals[0]
      if (!sessionId) throw new ChatboxCliUsageError('Missing session id.')
      const limit = integerFlag(parsed, 'limit', { defaultValue: 20, min: 1, max: 50 })
      const cursor = integerFlag(parsed, 'cursor', { defaultValue: 0, min: 0, max: 10_000_000 })
      const session = await chatStore.getSession(sessionId)
      if (!session) throw new ChatboxCliUsageError(`Conversation not found: ${sessionId}`)

      const messages = readableMessages(session)
      const page = messages.slice(cursor, cursor + limit)
      return {
        scope: 'session',
        session: { id: session.id, name: session.name, type: session.type ?? 'chat' },
        messages: page.map(({ message, thread }) => compactMessage(message, thread)),
        nextCursor: cursor + page.length < messages.length ? cursor + page.length : null,
        total: messages.length,
      }
    },
  },
]

View on GitHub (pinned to 81571269ad)

Solutions

1. Pass a session id as the first positional, e.g. ['chats','read','<sessionId>'].
2. List sessions first with ['chats','list'] to obtain a valid id when unknown.
3. Validate the id is a non-empty string in the caller before dispatching.

Example fix

// before
await executeChatboxCliCommand({ argv: ['chats', 'read'] }, ctx)

// after
if (!sessionId) return promptUser('Select a conversation')
await executeChatboxCliCommand({ argv: ['chats', 'read', sessionId] }, ctx)

const sessionId = String(rawId ?? '').trim()
if (!sessionId) {
  return { error: 'A session id is required', kind: 'usage' }
}
await executeChatboxCliCommand({ argv: ['chats', 'read', sessionId] }, ctx)

function isSessionId(input: unknown): input is string {
  return typeof input === 'string' && input.trim().length > 0
}

const res = await executeChatboxCliCommand({ argv: ['chats','read', id] }, ctx)
if (!res.ok && res.kind === 'usage' && res.error.startsWith('Missing session id')) {
  // prompt the user to select a conversation
}

When it happens

Trigger: Invoking chats read with no arguments, or with an empty first positional.

Common situations: An LLM tool-call that forgot the id, a UI button wired without a selected conversation, or a recovery script missing the id.

Related errors

• Missing search query.
• Conversation not found: ${sessionId}
• Image generation requires an active chat session.
• Missing --prompt.
• --style must be vivid or natural.

AI-assisted analysis of chatboxai/chatbox@81571269ad (2026-08-12). Data as JSON: /api/errors/a734f86a6be81cb0. Report an issue: GitHub.