ErrLookup › Background articles › Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them

Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them

Missing required parameter errors — 'model is required', 'The required X param is missing', 'Please provide userId or username', Yii's 'Missing required parameter $name when calling...' — fire when a call reaches the receiver without a value that can neither be defaulted, inferred, nor worked around. The family spans 191 documented records across 27 repositories: HTTP 400s from REST endpoints (Rocket.Chat, Nextcloud OCM federation, the LiteLLM proxy), ValueErrors raised client-side before any network traffic (LiteLLM provider handlers), CLI refusals (buzz-admin), DI container exceptions (Yii), and guard clauses in Rust services (CodeWhale, caveman). Developers meet it most often when serialization silently drops undefined or empty values, when a config-driven deployment leaves a required field unset, or when an internal handler is invoked directly instead of through the public wrapper that normally supplies the parameter.

Distilled from 191 documented records across 27 repositories.

Background

Every record in this family is a fail-fast guard on the receiving side: a handler, schema validator, config layer, or dependency-injection resolver refuses to proceed because it cannot do its work without the value. The receiver needs something concrete to act on — a roomId to look up (Rocket.Chat chat.syncMessages), a model id to route a provider request (LiteLLM bedrock and black_forest_labs image routes), a stable signing key to republish a channel snapshot (buzz-admin --channel), an expected role to audit a database identity against (caveman ValidateRuntimeIdentity) — and the check runs before side effects: Chroma's transactional delete rejects a None ids list before the server is called, LiteLLM's Pydantic AI handler raises before any HTTP traffic happens, and CodeWhale's memory store refuses a Workspace scope with no workspace id before any file is opened or the write lock is taken.

From the caller's side the error names the missing value, but vocabulary and strictness vary by library. Rocket.Chat handlers apply truthiness checks ('The required mid body param is missing', 'Please provide userId or username or userIds or usernames as param') and often run behind schemas with no minLength, so an empty string can pass validation and die only at the handler. LiteLLM's speech-to-completion bridge type-checks each kwarg ('model is required', 'headers is required', 'logging_obj is required') and rejects wrong types, not just absent keys — a unittest Mock fails the isinstance check for logging_obj. Yii's container reports exactly which parameter of which function was unresolvable, and only for scalars: class-typed parameters are autowired, scalar ones never are. The transport varies too — a Meteor.Error with no error code, a ValueError converted into a 400 ProxyException with a cosmetic 'Authentication Error' prefix, a BadRequestException on a federated OCM notification, or a Rust ErrorKind::InvalidInput.

Recurring quirks cut across libraries. Serialization loses values silently: JSON.stringify drops undefined keys, so a params object built from optional variables can lose roomId and roomName on both branches and ship as if never set. OR-contracts (roomId or roomName; user_id or user_email; type or lastUpdate; --relay-key or BUZZ_RELAY_PRIVATE_KEY) fail only when every alternative is absent — and some are asymmetric: Rocket.Chat's room resolver treats two empty strings as this error, but a lone empty roomId falls through to a lookup of '' and surfaces as error-room-not-found instead. None-versus-empty distinctions matter: LiteLLM's MCP tool-call entry accepts arguments={} yet rejects arguments=None, and its dall-e-2 model default applies only when both model and custom_llm_provider are absent, so a provider set without a model still reaches the guard. Parameter location matters: emoji-custom.update reads _id only from multipart form data and never sees it in a query string or JSON body.

A distinct sub-family sits at abstraction boundaries. LiteLLM's bridge kwargs (model, custom_llm_provider, headers, logging_obj), the Vertex video-edit transform's prefetched_source_data, and the api_base for Pydantic AI handlers are all supplied by public entry points such as litellm.speech() and litellm.video_edit(), which also perform prerequisite steps like prefetching the source operation. When those errors fire, the cause is usually not a forgotten payload field but a bypassed wrapper — direct handler calls, forked or refactored code paths, or tests with hand-built kwargs. Which check fires first is library- and version-specific: the records show both modern builds where schema validation rejects the omission up front and older builds where only the handler-level throw remains as defense-in-depth.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 171 more across the corpus — use search.

Honest provenance: generated on 2026-08-19 from AI-assisted analysis of the linked records. See how records are made.