ErrLookup › Background articles › "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires

"is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires

Errors like "source is not a compatible type", "failed to merge statements", and "instance is not a RGB image" all fire when a library checks a value's concrete type up front and refuses to proceed. These incompatible-source-type errors surface at config load, evaluation, scan, or deserialization time. Here is why they exist and how to fix them.

Distilled from 526 documented records across 65 repositories.

Background

This family covers a defensive pattern: a library accepts a value or reference, verifies its concrete type against what the operation actually needs, and fails fast with an explicit error instead of misbehaving later. In googleapis/mcp-toolbox, ValidateSource performs a type assertion against a private compatibleSource interface when a tool's source field in tools.yaml points at the wrong engine, catching the mistake at config load time. In deeplearning4j, OutputLayerUtil rejects classifier evaluation classes when the network's output layer is a Yolo2OutputLayer, because classifier metrics are meaningless for object detection. In tomnomnom/gron, the ungron path fails when recursive merge finds the same key path assigned incompatible container types (object vs array).

The checks appear at many layers. Some are config-time: mcp-toolbox validates the tools file at startup, and shadcn-ui's cn migration asserts declared tailwindcss and tailwind-merge versions in package.json before rewriting anything. Some are runtime validation: Yalantis/uCrop throws CImgInstanceException when RGBtoHSI is called on an image whose channel count is not 3, and cocoindex refuses to declare a vector index on a PostgreSQL column that is not a vector or halfvec type. Some sit at the data boundary: coder's sqlc-generated Scan methods only accept []byte or string for enum columns and return "unsupported scan type" for anything else a driver delivers, while microg's DataBundle reader rejects lists whose elements have mixed types during deserialization.

A notable sub-family guards filesystem invariants against concurrent modification. astrid-runtime aborts migration inventory when a file swapped to a symlink or fifo between the directory scan and the open (a TOCTOU guard), libnyanpasu refuses journal phase transitions when the destination path holds a symlink or non-regular file, and kopia's resolveSymlink gives up when a symlink chain lands on a directory or special file because ignore rules can only match file entries. owasp-amass is the outlier: its "%s is not compressed" detection error is informational by design and GetListFromFile deliberately swallows it, reading the file as plain text.

The failure is almost always treated as fatal, but the behaviour is library-specific: most of these checks abort the operation outright, while owasp-amass deliberately treats the mismatch as informational and continues. Exception classes vary by language — IllegalStateException and IllegalArgumentException dominate on the JVM — but the shape is identical: an up-front type check whose message usually names both what was found and what was required.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 506 more across the corpus — use search.

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