BoxLang + Lucee: photo model rejects file uploads — 'Cannot assign array value to scalar column fileData'

[bpamiri]

Describe the bug

Tests that exercise file-upload-into-blob-column on the Photo model error with:

Cannot assign a array value to scalar column \`fileData\` on the \`photo\` model.

(or lowercase filedata — same pattern, different DB-normalized column name).

This is not BoxLang-only — it also affects Lucee 6. 36 occurrences total across BoxLang (16) and Lucee 6 (20).

Evidence

Compat-matrix run #25837380625 (2026-05-13).

• BoxLang: 16 errors across cockroachdb, mysql, oracle, postgres
• Lucee 6: 20 errors across cockroachdb, h2, mysql, postgres, sqlserver
• Affected bundles:
  • wheels.tests.specs.model.crudSpec
  • wheels.tests.specs.global.internalSpec (the $hashedkey suite, which fixtures a Photo)

To Reproduce

1. Run wheels.tests.specs.global.internalSpec :: $hashedkey :: tests same output on either Lucee 6 or BoxLang against any DB except SQLite.
2. The test fixture attempts to populate Photo.fileData with binary data.
3. The model coerces the value to an array somewhere along the way, then the property setter rejects it because the column is scalar (blob).

Expected behavior

Binary file upload data assigned to a fileData (blob/longblob/bytea) column is stored without coercion errors, on every engine.

Root cause hypothesis (not yet confirmed)

CFML doesn't have a portable "bytes" type. Different engines surface binary content differently:

• Lucee returns java.nio.HeapByteBuffer or a byte[]
• Adobe returns byte[]
• BoxLang appears to surface binary as a CFML array

Wheels' model property assignment likely calls IsArray() or a similar check on the incoming value, sees the BoxLang-flavored binary as an array, and refuses the assignment for scalar columns.

The fact that SQLite passes on both engines is interesting — likely because the SQLite adapter coerces blobs to strings or accepts arrays without complaint, so the model's check never trips.

Suggested investigation order

1. Add a small reproducer that calls FileReadBinary() against a known asset on each engine and inspects the runtime type with getMetadata(val).getName().
2. If the engines surface different runtime types, either:
   • Add an engine-adapter helper that normalizes to a portable bytes representation, or
   • Relax the model's property-assignment type check to accept array-of-bytes when the column is binary.
3. Pure test fix may also be possible if the fixture is what's producing the array shape — check tests/_assets/... for how Photo is being constructed.

Suggested fix shape

Medium effort — needs investigation to choose between (a) engine adapter binary normalization or (b) test fixture rewrite. Either is one PR.

Additional context

• Part of the Core test suite has high failure/error rate on BoxLang (35 failures, 125 errors, 3526 passing) #2649 decomposition (Tier 2). Cross-engine — not BoxLang-only, despite being surfaced through the BoxLang failure clustering.
• The lowercase-vs-mixed-case (fileData vs filedata) split is just DB column-name normalization (PostgreSQL lowercases unquoted identifiers; MySQL keeps the original casing). Same bug; column-name presentation differs by adapter.

Related: #2649

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

model — see .ai/wheels/models/ for canonical patterns. The error message originates in vendor/wheels/model/properties.cfc:588, inside the property-assignment branch that rejects array/struct values when the target is a scalar DB column.

Fix sketch

The guard at vendor/wheels/model/properties.cfc:580-590 rejects any array value bound for a scalar column without consulting the column's underlying SQL type. When FileReadBinary() / multipart upload data surfaces as a CFML array (BoxLang's binary representation, and apparently Lucee 6 in some configurations), the assignment is rejected even though the target column is a blob / longblob / bytea. Two plausible fix shapes, picked in propose-fix:

(a) Engine-adapter normalization — add a coerceBinaryValue(value) helper on wheels.model.adapters.<Engine> that converts array-of-bytes to the engine-native byte buffer before assignment. Called from $setProperty (or its caller) when the column's type is binary. Keeps the scalar-column guard intact.

(b) Relax the guard for binary columns — in the IsStruct || IsArray branch, look up variables.wheels.class.properties[property].type and bypass the throw when the column type is binary / blob / longblob / bytea. Cheaper, but punts the engine-normalization question to the JDBC driver, which may still mis-bind on some adapters.

A third possibility is that the test fixture in tests/_assets/ (or vendor/wheels/tests/_assets/) is constructing Photo.fileData from a path/array that's already wrong-shaped on those engines — propose-fix should confirm by tracing the fixture before changing framework code. The fact that SQLite passes on both engines is consistent with the SQLite adapter being lenient about array-shaped binary inputs.

Confidence: medium

Cross-engine concern detected (BoxLang vs Lucee 6 vs Lucee 7 vs Adobe surface binary differently per CLAUDE.md § "Known cross-engine gotchas") — auto-downgraded from high to medium per the rules. The layer and offending line are unambiguous, but the fix path requires choosing between engine-adapter normalization and a typed-column carve-out, plus confirming whether the fixture is at fault.

<!-- wheels-bot:triage:2660 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2668

Spec: vendor/wheels/tests/specs/model/binaryPropertyAssignmentSpec.cfc — failing → passing
Implementation: vendor/wheels/model/properties.cfc ($setProperty guard + new $propertyIsBinaryColumn helper)

Local tools/test-local.sh could not run in the propose-fix sandbox (no wheels CLI installed there); CI's compat-matrix will validate the spec on every engine × every DB combination this issue references.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.