Troubleshooting
Use the symptom sections below to diagnose installation, compilation, data-conversion, and runtime problems. For build or loading failures, record the full compiler and SDK paths: a version string can hide a different runtime or LLVM build selected through the environment.
Modules or Libraries Cannot Be Found
Codon Cannot Import exaloop Modules
Each native exaloop module is supplied by its SDK, not by a Python package.
For exaloop.data, use -plugin /path/to/sdk/data; for
exaloop.databases.mysql, use -plugin /path/to/sdk/mysql. Repeat -plugin
when an application needs multiple SDKs. With the CLI, register the SDK and
select it with --with NAME or the target's plugins list. See
import paths and registration.
If a generated Protobuf module cannot be imported, check that all imported schemas were generated and that their original directory structure is intact. The generated package root must be visible to Codon.
A Plugin Is Rejected or Has Missing Symbols
Check that the compiler, standard library, runtime libraries, and plugin were
built for compatible versions and architectures. This can happen when a shell
finds one compiler on PATH but library search paths select another runtime.
The distribution supplies a matched set; exaloop distribution verify checks
the integrity of that installation.
For the optimizer, the plugin must match the selected Codon compiler's LLVM build. A different system or Homebrew LLVM may have the right version number without matching its ABI. The optimizer included with the supplied distribution avoids this mismatch.
If an executable works locally but fails after deployment, check shared-library discovery on the destination as well as its architecture and operating-system deployment target. Native applications still need their matching runtime libraries.
Profiling or PGO Does Not Run
Run exaloop doctor --profiling or exaloop doctor --optimization first.
These exercise the native capture or PGO path; metadata and matching version
numbers alone cannot establish compatibility. Check the selected SDK and
compiler paths, and use a supported native target. Database-hosted functions
are not supported by these workflows.
For PGO, configure separate train, tune, and holdout argument arrays under
targets.NAME.optimize. A baseline selection is not a failed build: inspect the
report for insufficient gain, regression, memory/code limits, holdout rejection,
or an exhausted budget. Short or noisy workloads may need longer representative
cases. Correctness checks remain necessary even when a candidate appears faster;
a performance gain is useful only when the application still produces valid results.
See the PGO walkthrough and settings reference.
Installation Verification Fails
An archive checksum mismatch means the file differs from the tarball identified by Exaloop's supplied checksum. Verification should succeed before any extracted tool is executed. If a fresh copy still fails, your Exaloop contact can confirm the correct archive and checksum for the selected platform.
For an installed distribution, a failed exaloop distribution verify can indicate
missing or modified files. The installation guide
describes local-archive installation and rollback; the support guide
lists the diagnostics useful when an installed release cannot be verified.
Arrow Conversions and Formats
An empty or all-null array still has an Arrow type. If conversion fails, request
that exact type: i32 for int32, for example, rather than the 64-bit int.
Use cast(T) when changing the type is intended. For missing values, use
Optional[T] with list/item access, or to_numpy_masked(T) for a numeric array.
On a dictionary-encoded array, is_null() examines the index validity bitmap.
A valid index can point to a null dictionary value, so the decoded missing-value
mask may differ. See Arrow conversion.
If data unexpectedly changes when using copy=False, check the original input.
Borrowed numeric storage must not be mutated or resized while Arrow uses it.
The default snapshot behavior is a better choice for input that will change.
Format support also differs. JSON is input-only and expects newline-delimited objects. ORC and CSV cannot represent every Arrow type; IPC is often useful when preserving a richer schema. A cast can help only when the converted value has the meaning your application needs.
Protobuf Mutation and Presence
For a generated repeated message or message-valued map, update the returned
child or call CopyFrom() on it. Direct element assignment follows different
rules from scalar collections. The message reference
lists supported operations.
has() reports explicit presence, not whether a value differs from its default.
Proto3 implicit scalar fields and repeated fields do not support that check.
In the runtime reflection API, get_message() returns a copy. Write a changed
child back with set_message() to update its parent. Generated messages instead
expose live children, which is why the two APIs behave differently here.
Closed Handles and Command Lifetimes
Aliases of an Arrow or dynamic Protobuf handle share its closed state. Closing one alias closes the others. Separately extracted Arrow columns and slices, and dynamic Protobuf child copies, own independent handles and can outlive a parent.
In Redis, contexts, argument views, and replies are only valid during the current
command. Save copied values rather than those handles. Unloading a Codon module
is disabled; restart Redis to replace it. Key-access errors often
mean a handler's keys declaration does not include the key it tried to access.
See Redis registration.
Contact Support
The support guide lists useful diagnostics and explains which information may need redaction before sharing.