github/copilot-sdk · error · IllegalStateException

Failed to serialize FFI JSON parameter.

Error message

Failed to serialize FFI JSON parameter.

What it means

jsonBytes() serializes the argv/env payloads with Jackson before passing them to the native layer. Jackson's writeValueAsString threw JsonProcessingException (e.g. infinite recursion, unserializable type), which the library converts to IllegalStateException because it indicates a programming error, not a runtime condition.

Solutions

1. Inspect the attached JsonProcessingException cause for the offending property.
2. Ensure CopilotClientOptions contains only simple serializable values (String, int, boolean, Map, List).
3. Add @JsonIgnore to transient/non-serializable fields.
4. Pin a compatible Jackson databind version.

Example fix

// before
class Options extends CopilotClientOptions { InputStream debugStream; }
// after
class Options extends CopilotClientOptions {
    @JsonIgnore transient InputStream debugStream;
}

new ObjectMapper().writeValueAsString(options); // validate serializability before start()

boolean serializable(Object o) { try { MAPPER.writeValueAsString(o); return true; } catch (JsonProcessingException e) { return false; } }

try { host.start(e, o); } catch (IllegalStateException ex) { if (ex.getCause() instanceof JsonProcessingException jpe) { log.error("unserializable option: " + jpe.getMessage()); } throw ex; }

When it happens

Trigger: buildArgvJson or buildEnvJson given an options object graph Jackson cannot serialize: self-referencing structures, custom types without serializers, or a malformed CopilotClientOptions implementation.

Common situations: Subclassing/monkey-patching options with unserializable fields (streams, lambdas with cycles); mixing Jackson versions where a custom serializer is incompatible.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Failed to coerce parameter ' + param.name() + ' to type +…
• Failed to apply default value ' + defaultValue + ' for…
• Invalid schema JSON for parameter ' + param.name() + ' in…
• Failed to serialize tool result to JSON
• Failed to deserialize arguments to + type.getName()

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/cf8fb2adead796b5. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java:345

        String copilotHome = options.getCopilotHome();
        if (copilotHome != null && !copilotHome.isEmpty()) {
            env.put("COPILOT_HOME", copilotHome);
        }
        if (options.getMode() == CopilotClientMode.EMPTY) {
            env.put("COPILOT_DISABLE_KEYTAR", "1");
        }

        if (env.isEmpty()) {
            return null;
        }
        return jsonBytes(env);
    }

    private static byte[] jsonBytes(Object value) {
        try {
            return MAPPER.writeValueAsString(value).getBytes(StandardCharsets.UTF_8);
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("Failed to serialize FFI JSON parameter.", e);
        }
    }
}

View on GitHub (pinned to cd8cf15dc3)