{"record":{"id":"dbd0cd8c80103f6f","repo":"phalcon/cphalcon","slug":"invalid-sql-list-expression","errorCode":null,"errorMessage":"Invalid SQL-list expression","messagePattern":"Invalid SQL-list expression","errorType":"exception","errorClass":"InvalidListExpression","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Dialect.zep","lineNumber":1284,"sourceCode":"\n        if isset expression[\"separator\"] {\n            let separator = expression[\"separator\"];\n        }\n\n        if (fetch values, expression[0] || fetch values, expression[\"value\"]) && typeof values == \"array\" {\n\n            for item in values {\n                let items[] = this->getSqlExpression(item, escapeChar, bindCounts);\n            }\n\n            if isset expression[\"parentheses\"] && expression[\"parentheses\"] === false {\n                return join(separator, items);\n            }\n\n            return \"(\" . join(separator, items) . \")\";\n        }\n\n        throw new InvalidListExpression();\n    }\n\n    /**\n     * Resolve object expressions\n     *\n     * @param array expression\n     * @param string|null escapeChar\n     * @param array bindCounts\n     *\n     * @return string\n     */\n    final protected function getSqlExpressionObject( array expression, string escapeChar = null,  array bindCounts = []) -> string\n    {\n        var domain = null, objectExpression;\n\n        let objectExpression = [\n            \"type\": \"all\"\n        ];","sourceCodeStart":1266,"sourceCodeEnd":1302,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect.zep#L1266-L1302","documentation":"getSqlExpressionList() throws InvalidListExpression when a 'list'-type expression cannot be resolved: it requires either a numeric element 0 or a 'value' key holding an array of items. If neither key exists, or the fetched value is not an array (e.g. a string or null), the expression is not a valid list and the compiler throws instead of emitting broken SQL.","triggerScenarios":"Passing ['type' => 'list', 'value' => '1,2,3'] (string instead of array); a list expression with items stored under a different key ('values', 'items'); an empty/aliased array where fetch of both expression[0] and expression['value'] fails; nested expression data built by your own query layer that forgets the 'value' key.","commonSituations":"Custom IN() expression builders; deserializing expression arrays from JSON where the list payload got flattened; upgrading from code that constructed list expressions ad hoc against an older dialect.","solutions":["Give the list expression an array payload: ['type' => 'list', 'value' => [1, 2, 3]] or the numeric form [ ['type' => 'list'], [1, 2, 3] ]","Normalize before compiling: if (isset($expr['type']) && $expr['type'] === 'list') { $expr['value'] = (array) ($expr['value'] ?? []); }","For IN clauses prefer the Query Builder / PHQL IN operator which produces correct list expressions"],"exampleFix":"// before\n$expr = ['type' => 'list', 'value' => '1,2,3'];\n\n// after\n$expr = ['type' => 'list', 'value' => [1, 2, 3]];","handlingStrategy":"validation","validationCode":"if (($expr['type'] ?? null) === 'list') {\n    $values = $expr[0] ?? $expr['value'] ?? null;\n    if (!is_array($values)) {\n        throw new InvalidArgumentException('List expression requires an array payload under \"value\"');\n    }\n}","typeGuard":"function isValidListExpression(array $expr): bool\n{\n    if (($expr['type'] ?? null) !== 'list') {\n        return true; // not a list, nothing to check here\n    }\n    $values = $expr[0] ?? $expr['value'] ?? null;\n    return is_array($values);\n}","tryCatchPattern":"try {\n    $sql = $dialect->select($definition);\n} catch (\\Phalcon\\Db\\Exceptions\\InvalidListExpression $e) {\n    throw new InvalidArgumentException('List expression missing array payload', 0, $e);\n}","preventionTips":["Always build list expressions as ['type' => 'list', 'value' => [...]]","Cast comma-separated user input to arrays before embedding","Re-validate deserialized expression arrays before compiling"],"tags":["phalcon","sql","dialect","expression-array","in-list"],"backgroundTag":"invalid-sql-expression","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}