Troubleshooting

Start with the symptom below. For a source error, run kalandra-check on the same source or manifest first. For an installation or compiler error, record kalandra --version and the command you ran.

A command is not found

Add the installed toolchain's bin directory to PATH and open a new terminal. On Windows, use a Visual Studio developer shell with the C++ tools and Windows SDK configured. Confirm that you downloaded a compiler package rather than only an editor package.

The compiler cannot find its resources

Keep the complete installed directory together, including bin, lib, libexec and share. Copying kalandra alone is insufficient. Use the package for your build computer and chosen backend: Metal on supported Macs, or the appropriate CUDA/Vulkan package on Linux or Windows. External-toolchain packages also require the dependency paths listed in their metadata.

A project or import cannot be found

Pass --project explicitly; the compiler does not search parent directories. Manifest paths resolve from the manifest directory, command-line output paths from the current directory, and relative source imports from their declaring file. Include .k on relative imports and export the declarations you import.

For managed dependencies, run install explicitly before checking or building. A changed manifest, missing lock or modified dependency snapshot can prevent a build from using its dependencies. Frozen offline mode cannot download a missing snapshot.

Two numeric values will not combine

Give compatible literals an expected type, or convert typed values explicitly. This example intentionally fails because it mixes already typed widths:

fn main() -> int64:
  narrow: int32 = 40
  wide: int64 = 2
  narrow + wide

The corrected complete program returns 42:

fn main() -> int64:
  narrow: int32 = 40
  wide: int64 = 2
  int64(narrow) + wide

Use an explicit conversion if the intended operation is int64 arithmetic. An explicit conversion is checked and is not a general promise that every destination can represent every value.

An array is read-only or has an unfinished reader

Ordinary array parameters and captured arrays do not grant write access. If a helper must write its caller's numeric or Bool array, declare a mut parameter. If it only needs a private working array, call copy and edit the result.

A task can still read storage after the parent gives it another local name or replaces its own binding. Await every relevant reader before editing the old storage. An await in only one branch or inside a loop that might run zero times does not prove the task has finished. A spawned task cannot request mut access to parent-provided arrays.

• Array sharing, aliases and write access

A tensor has the wrong shape

Check every dimension, not only the total element count. Elementwise tensor operations need compatible complete shapes, and matmul requires rank two with matching inner dimensions. A ? dimension accepts a runtime extent but does not disable checking. reshape changes shape deliberately while preserving element count.

A GPU value cannot be used on the CPU

Awaiting a tensor-producing GPU task keeps the tensor resident. Transfer it to devices.cpu() before host operations, or pass it directly to another eligible GPU task. Check that the Apple SDK and the pinned Metal compiler are installed when compilation fails before execution.

A GPU backend or arithmetic mode is unavailable

Confirm that the installed compiler package includes the backend selected by --target and that its prerequisites are installed. A CPU-only package cannot compile GPU code merely by adding a backend flag. Windows GPU packages remain experimental.

For Metal float64 arithmetic, select --arithmetic hardware-with-software-fallback explicitly or use a supported float32 calculation. Do not change precision just to silence an error unless that precision suits your application. GPU row normalization requires hardware float32 and does not accept software arithmetic.

• Packages and backend prerequisites
• Arithmetic and matrix policies

A GPU program displays hexadecimal digits

The Metal executable displays floating results as IEEE-754 bit patterns. For example, float32 23 is displayed as 41b80000. This is the result representation, not an error or an integer conversion. Compare with the expected display given beside the GPU example.

Parallel work is slower than a normal call

Scheduling, transfers and device dispatch have costs. Start independent tasks before awaiting them, retain GPU intermediates where useful and measure with realistic sizes. Adding spawn to every tiny operation is not a speedup guarantee.

An array literal after an indented expression is rejected

An array literal immediately after a binding with an indented body, such as a parallel block, can be interpreted as indexing the preceding expression. Bind the intended output array to a new name, then return that name. Keep the array's binding at the same indentation level as the enclosing result.

Editor results look stale

Check the native server path, Workspace Trust and explicit project setting. Restart the language server after changing manifest contents or rebuilding the server. Use its output command for diagnostics. The extension handles local file workspaces; unsupported remote/virtual workspace behavior should not be assumed.

• Platform prerequisites
• Expected errors and task failures

Report a problem

If these steps do not resolve the problem, open an issue with the smallest source example that reproduces it, the full command, expected and actual behavior, toolchain version and operating system. For a GPU issue, include the backend, GPU model, driver version where applicable, and arithmetic flags. Remove private data and credentials before sharing logs or source.

• Report a Kalandra bug