The 100-Argument Wall: Unpacking PostgreSQL’s Most Obscure and Stubborn Limit
To most database administrators and software engineers, max_function_args is a phantom. It is never queried on purpose, nor is it a configuration parameter that anyone actively seeks to tune during performance optimization passes. Instead, developers typically encounter it by surprise—usually when PostgreSQL interrupts an otherwise unrelated operation with the abrupt and unyielding error message: cannot pass more than 100 arguments to a function.
When a developer attempts to resolve this issue by searching for the corresponding configuration knob in postgresql.conf, they hit a dead end. There is no knob.
This read-only preset—a close architectural sibling to foundational parameters like block_size and integer_datetimes—operates within an internal context. Any attempt to modify it via standard administrative commands such as SET, ALTER SYSTEM, or a direct line in postgresql.conf results in a definitive rejection: parameter "max_function_args" cannot be changed. Querying the system catalog view pg_settings reveals a min_val and a max_val both fixed strictly at 100, creating a functional range with only a single member.
Under the hood, this value mirrors FUNC_MAX_ARGS, a constant defined in the source file src/include/pg_config_manual.h. Remarkably, this limit has remained locked at 100 since the release of PostgreSQL 8.1. While modern hardware boasts massive multi-core processors, terabytes of RAM, and blazing-fast NVMe storage arrays, this two-decade-old software boundary remains completely static.
Understanding why this limit exists requires diving deep into the relational database’s historical architecture, its catalog plumbing, and the modern engineering realities that keep the cap firmly in place.
Chronology: From Shared Table Keys to the Modern Era
To trace the lineage of max_function_args, one must travel back to the early 2000s, an era when PostgreSQL’s internal storage models and catalog schemas were vastly different.
Prior to PostgreSQL 8.1, FUNC_MAX_ARGS was not defined as an independent, standalone number. Through version 8.0, the macro was explicitly #defined as INDEX_MAX_KEYS, accompanied by source code comments insisting that the two constants "must be the same value."
This rigid coupling was driven by fundamental catalog plumbing constraints. In early versions, oidvector was implemented as a fixed-width C array consisting of INDEX_MAX_KEYS Object Identifiers (OIDs). Crucially, this single data type served a dual purpose: it was used for both pg_index.indclass (defining index column classes) and pg_proc.proargtypes (defining procedure argument types). Because a single fixed width was used for both system catalogs, the argument limit for functions was forced to match the index key limit.
Consequently, the function argument limit fluctuated with storage capabilities:
- PostgreSQL 7.2: The limit stood at 16.
- PostgreSQL 7.3: The limit was expanded to 32.
- PostgreSQL 8.0: The General Utility Control (GUC) parameter reporting the limit appeared for the first time, proudly announcing a cap of 32.
The 2005 Decoupling
The paradigm shifted in March 2005, when core PostgreSQL developer Tom Lane refactored oidvector and int2vector into variable-length arrays (known internally as varlenas). This architectural cleanup severed the technical dependency that forced function arguments and index keys to share the exact same dimensional limits.
Just hours after decoupling the systems, Lane updated FUNC_MAX_ARGS to 100.
Why 100 and not a higher figure, such as 500 or 1,000? In discussions on the pgsql-hackers mailing list, Lane explained his rationale. At the time, the PostgreSQL codebase was heavily peppered with MemSet function calls that explicitly cleared memory allocations sized to FUNC_MAX_ARGS. Setting the limit to 100 was a safe, empirically tested threshold that could be achieved without introducing performance degradation or memory fragmentation pain points. Meanwhile, index keys remained capped at 32, creating a permanent divergence that lives on today through the separate parameter max_index_keys.
Supporting Data: The Evolution of Memory Structures
Lane’s caution regarding MemSet calls was entirely justified, and the performance implications of that architectural decision outlived the initial change by nearly a decade and a half.
Until the release of PostgreSQL 12, FunctionCallInfoData—the core C struct through which every V1-compliant function receives its arguments—carried two fixed-size arrays matching the size of FUNC_MAX_ARGS. One array stored the argument values (Datum), while the other stored their null flags (bool).
Because of this rigid design, even a trivial, two-argument system call like int4pl (integer addition) forced the server to allocate and pass a bulky 936-byte struct on x86-64 architectures.
The Freund Rewrite in PostgreSQL 12
This memory inefficiency was finally addressed when core developer Andres Freund executed a sweeping rewrite for PostgreSQL 12. Freund converted the struct into a variable-length allocation. Today, that same two-argument integer addition call passes a lean 64-byte struct instead.
Despite these modernizations, remnants of the FUNC_MAX_ARGS constant persist in specific code paths—primarily as stack-allocated arrays within the SQL parser and in execution routines where the exact argument count cannot be determined safely at compile time.
However, because the constant has not been tied to the on-disk storage format since 2005, the C header files have noted since version 8.1 that raising the limit does not require running initdb.
Official Responses and Enforcement Points
When a developer attempts to bypass or exceed the 100-argument ceiling, PostgreSQL enforces the boundary across two distinct code paths, generating different error messages depending on the context.
1. Procedure and Function Creation (ProcedureCreate)
When executing a CREATE FUNCTION or CREATE PROCEDURE statement, the backend counts the input parameters (IN).
- Note:
OUTparameters are explicitly excluded from this calculation. A developer can successfully define a function featuring 100INparameters and threeOUTparameters without triggering an error. - However, attempting to declare a 101st
INparameter causesProcedureCreateto reject the statement with the explicit message:functions cannot have more than 100 arguments. - Interestingly, attempting to register a stored procedure with 101 parameters yields the exact same wording, despite internal source comments containing a distinct error string (
procedures cannot have more than 100 arguments) reserved exclusively forDROPoperations. - For aggregate functions, the limit is effectively 99, because the aggregate’s transition function reserves its very first argument to maintain internal state.
2. The SQL Parser (ParseFuncOrColumn)
The second and far more common enforcement point is the SQL parser, which users hit in everyday application development.
Before the parser resolves function overloading, determines data types, or executes downstream planning, ParseFuncOrColumn inspects the raw argument list. This early validation is necessary because the rest of the parsing engine relies on stack-allocated Oid arrays sized to FUNC_MAX_ARGS and seeks to prevent dangerous buffer overruns.
Consequently, the error message cannot pass more than 100 arguments to a function (associated with SQLSTATE 54023, categorized as too_many_arguments) fires based strictly on the literal count of items enclosed within the parentheses. Crucially, this rule applies even to variadic functions, whose entire architectural purpose is to accept an indefinite, dynamic number of arguments.
Real-World Breaking Points
This rigid parser behavior creates predictable traps for developers:
- Calling a variadic function like
concat()with 101 individual strings will immediately fail. - Executing the
format()function with a format string containing one hundred placeholders plus the format string itself (totaling 101 arguments) will fail. - Using
jsonb_build_object(), which accepts interleaved key-value pairs, fails at the 51st pair (totaling 102 arguments).
The JSON builder scenario is the most frequent vector by which modern developers encounter the limit. A production database table gradually grows its 51st column over years of feature updates. An Object-Relational Mapping (ORM) framework—designed to dynamically project related table rows into a JSON document—emits an automated query invoking jsonb_build_object('id', t.id, 'name', t.name, ...). The moment the argument count ticks past 100, a query that has executed successfully since the inception of the project halts permanently.
A formal bug report submitted to the PostgreSQL community in 2020 requested that the limit be raised to 500 specifically to accommodate these ORM-generated JSON queries. The core maintainers delivered the expected, pragmatic answer: No.
What Is Exempt From the Limit?
Interestingly, the 100-argument cap does not apply to syntax constructs that look like function calls to the casual observer, but are parsed as distinct expression nodes by the engine. Built-in constructs such as COALESCE, GREATEST, LEAST, ROW(...), ARRAY[...], and x IN (...) are handled natively by parser grammar rules. Bench testing against PostgreSQL 18.6 confirms that feeding 500 arguments into these expression nodes executes without complaint.
Implications and Architectural Workarounds
For developers facing the too_many_arguments wall, attempting to recompile the database server is rarely a viable production strategy. The solution must be implemented on the client side of the database socket.
The Array and Row Solution
The golden rule for bypassing the limit is simple: pass a single argument that encapsulates many items.
- Variadic Arrays: Wrapping arguments in an explicit array structure allows the parser to treat them as a single entity. For instance,
concat(VARIADIC ARRAY[...])andjsonb_build_object(VARIADIC ARRAY[...])successfully bypass the literal argument count. However, developers must mind data typing constraints: standard SQL arrays require a uniform element type, meaning mixed keys and values must be coerced to text, resulting in JSON values rendered strictly as strings. - Whole-Row Variables: For wide-table JSON serialization cases, replacing sprawling key-value lists with
to_jsonb(t)passes the entire table row as a single, type-safe argument. Unwanted columns can then be stripped dynamically using the JSONB subtraction (-) operator. - Composite Types and Documents: When migrating legacy stored procedures from enterprise platforms like Oracle or Microsoft SQL Server that rely on 150+ input parameters, developers should refactor the interface to accept a structured composite type or a unified
jsonbdocument payload.
As Tom Lane advised a developer struggling with a 65-argument PL/pgSQL function back in 2006: rethink the API. That design principle remains entirely valid today.
Can You Actually Raise the Limit?
In theory, raising max_function_args is entirely possible. It requires a single-line edit in src/include/pg_config_manual.h.
The header file technically permits values ranging from a minimum of 8 (required because GIN index support functions accept eight arguments) up to roughly 600 (governed by the maximum physical capacity of the pg_proc index tuple to hold an argument-type vector). As noted earlier, no initdb is required to effect the change.
However, executing this change in a production environment introduces a severe operational penalty: every single C-based extension installed on the machine must be recompiled.
Since PostgreSQL 8.2, the internal PG_MODULE_MAGIC block embeds the compile-time value of FUNC_MAX_ARGS. During runtime, the dynamic module manager (dfmgr.c) validates this magic block when loading shared libraries.
Attempting to load a standard extension—such as pg_stat_statements—compiled against the default limit of 100 into a server modified to run a limit of 200 results in an immediate crash at load time:
postgres=# LOAD '/usr/lib/postgresql/18/lib/pg_stat_statements.so';
ERROR: incompatible library "/usr/lib/postgresql/18/lib/pg_stat_statements.so": magic block mismatch
DETAIL: Server has FUNC_MAX_ARGS = 200, library has 100.Popular extensions like PostGIS, pgvector, and every standard contrib module face the exact same binary compatibility barrier. Furthermore, in managed cloud database services (such as AWS RDS, Google Cloud SQL, or Azure Database for PostgreSQL), modifying compile-time constants is structurally impossible because users do not build the underlying server binaries.
Conclusion
The number is 100. It has remained 100 for two decades, and virtually no production database administrator will ever operate a standard server where it is set to anything else.
When a query demands 101 arguments, it is fundamentally asking for a collection rather than a discrete list. Package that data into a collection, pass it cleanly, and the 100-argument limit will recede back into the background—remaining, as it always has, a rule nobody looks up until it saves them from an unwieldy API design.
