In-memory execution and Hypertube exceptions

This article covers runtime and environment failures when host=inmemory. It assumes the installed graft package is correct. For missing members, stale packages, or Vision mismatches, see Module, method, or type is missing and Installed package is stale.

Symptoms

• The Caller defaults to host=inmemory but cannot load the Receiver module, embedded runtime, or native bridge.
• The first call fails with HypertubeException, FileNotFound, or native launcher exception codes.
• Receiver user-code exceptions (for example division by zero) appear wrapped in the Caller runtime.
• Configuration or environment changes appear to have no effect until the Caller process restarts.
• Transport errors (WebSocket, TLS, connection refused) appear even though you expected in-memory execution.

In-memory execution runs the Receiver inside the Caller process. Hypertube still marshals arguments and results through its protocol. Failures covered here originate in Caller configuration, embedded runtime bootstrap, module resolution, protocol/version mismatch, or Receiver user code — not in graft generation.

Prerequisites for in-memory execution

Before interpreting Hypertube messages, confirm the Caller process can embed the Receiver runtime and resolve the Receiver artifact.

Generated Graft defaults

Generated packages default host / Host to inmemory. The installed package must include the Receiver module for the target ecosystem, or you must configure a remote ws:// / wss:// host before the first call. See Set the module path for in-memory execution.

Hypertube activation

In-memory mode embeds Hypertube native runtimes in the Caller process. Activation is required before the first call.

If activation is missing or invalid, failures often appear as Hypertube not active, License invalid, or native Exception code 031 before any Receiver method runs.

Embedded Receiver runtime paths

When the Caller technology differs from the Receiver technology (for example Python calling Ruby), Hypertube must locate the Receiver's native runtime library on the machine. Set paths in the Caller process before the first graft call.

Resolution order for most runtimes:

1. runtimePath in the Hypertube configuration file (graftcode-config.json or package config) for the Receiver channel
2. Technology-specific environment variable (below)
3. Platform defaults (for example JAVA_HOME for JVM)

Configuration file alternative — set channel.runtimePath per Receiver runtime in graftcode-config.json:

{
  "licenseKey": "<your-hypertube-key>",
  "runtimes": {
    "ruby": {
      "name": "default",
      "modules": "<receiver-module-path>",
      "channel": {
        "type": "inMemory",
        "runtimePath": "C:/Ruby34-x64/bin/x64-ucrt-ruby340.dll"
      }
    }
  }
}

On Linux or macOS, use the corresponding .so or .dylib path. Prefer absolute paths in CI, containers, and multi-user hosts where the runtime is not on the default search path.

See Environment variable reference for the full variable list and copy-paste samples per platform.

Restart the Caller after changing host, module path, runtimePath, or environment variables. Generated runtime context is cached after first initialization.

Diagnostics

1. Confirm execution mode. Read the resolved host. inmemory / in-memory selects in-process execution. ws://, wss://, tcp://, or HTTP/2 hosts select network transport instead.
2. Verify module path and package contents. For in-memory mode, the Receiver artifact must be resolvable from the generated GraftConfig.module / modules setting or the installed graft package layout.
3. Check configuration precedence. Environment variables override files and generated defaults. A stale higher-priority value can keep the Caller on the wrong host or module path.
4. Capture the first complete exception. Preserve the outer Caller type (for example HypertubeException in Python) and the inner Receiver message. Hypertube rehydrates callee exceptions on the Caller side.
5. Identify the bootstrap stage. Note whether the failure happened during activation, embedded runtime load, loadLibrary, getType, or result serialization.
6. Enable diagnostics only in controlled environments.

export GG_DEBUG=1
export HYPERTUBE_RUBY_RUNTIME_PATH=/opt/ruby/lib/libruby.so
export HYPERTUBE_KEY=<your-key>

Redact captured logs before sharing. Disable debug switches after diagnosis.

Hypertube exception catalog (in-memory)

The table lists runtime and environment messages when host=inmemory. Exact wording can vary slightly by Caller runtime. Inner types are shown for Python; other SDKs map the same protocol codes to native types.

Configuration and bootstrap

Hypertube not active. Activate Hypertube before first use

License key not found in configuration source

Cannot load module: Library not found: {path}

Cannot find Ruby installed on this machine

Cannot find Python installed on this machine

currentCommand is undefined in InvocationContext execute method

Module and type loading (loadLibrary / getType)

These messages mean Hypertube could not load the Receiver module or resolve a type from the deployed artifact — not that the graft API surface is wrong.

Type {name} not found in .NET assemblies

Type: {name} not found in include path

Callee exceptions propagated through Hypertube

Receiver user code exceptions are serialized and re-thrown on the Caller. This is expected behavior when the Receiver logic fails at runtime.

Do not retry domain failures (validation, divide by zero, business rule violations). Fix Receiver logic or Caller inputs.

Protocol, version, and serialization

Type {type} is not supported for serialization.

Array index list must not be empty

Array index must be an integer

When the error is not in-memory specific

If you expected in-memory execution but see transport errors, inspect resolved host and environment overrides.

Fixes

• Missing embedded runtime: set HYPERTUBE_*_RUNTIME_PATH (or JAVA_HOME / PHP_HOME) in the same process that runs the Caller, then restart. On Windows, point at the .dll; on Linux/macOS, at the .so / .dylib.
• Missing activation: set HYPERTUBE_KEY or licenseKey in graftcode-config.json, then restart.
• Wrong module for in-memory: configure GraftConfig.module / modules and verify the Receiver artifact exists at that path. See Set the module path for in-memory execution.
• Accidental remote host: set host to inmemory before first call, or configure the intended ws:// Gateway URL explicitly.
• Hypertube version skew: align Caller SDK, embedded native binaries, and Receiver-side Hypertube versions from the same release.

Data to collect before reporting

1. Resolved host, module / modules, and configuration source (env, file, code).
2. Caller runtime and Hypertube dependency versions.
3. Receiver runtime version and deployed artifact paths.
4. Full outer and inner exception text (redact secrets).
5. Bootstrap stage: activation, runtime load, loadLibrary, getType, or serialization.
6. Values set for HYPERTUBE_KEY, HYPERTUBE_*_RUNTIME_PATH, JAVA_HOME, and runtimePath in config.
7. OS and architecture (Windows/Linux/macOS, x64/arm64).

Next steps

• Connection, timeout, or authentication failure — when the resolved host is remote, not inmemory
• Module, method, or type is missing — graft surface or discovery issues (outside this article's scope)
• Debug Graft invocations — GG_DEBUG, Vision, and staged checks
• Environment variable reference — activation, runtime paths, and diagnostic variables
• In-memory, same-machine, and remote execution — execution-mode terminology