Error Codes and Diagnostics

The Android SDK errors live in two worlds: host-side negative codes (problems detected by the facade) and engine-side positive codes (faults reported from native). SUCCESS = 0 is a genuine success return — it is not the same as “no error was set.”

Host-side negative codes (facade-detected problems)

Initialization (-1xxx)

Code	Meaning	On-site action
`-1000 ERR_INIT_FAILED`	Generic initialization failure	Check logcat for an earlier native cause first
`-1001 ERR_INVALID_SURFACE`	Surface is null or invalid	The Surface must be alive — commonly triggered by reusing the original surface after `surfaceDestroyed`
`-1002 ERR_INVALID_CONFIG`	RuntimeConfig is null or invalid	Confirm no mutation after `Builder.build()`
`-1003 ERR_NATIVE_LOAD_FAILED`	Native library failed to load	Call `MigoRuntime.getNativeLoadError()` and verify the `.so` naming across all ABI splits and the install package
`-1004 ERR_INVALID_GAME_ID`	`gameId` or `entryPoint` is missing	The game identifier and entry script name are defined by the content side; neither may be empty
`-1005 ERR_NOT_SUPPORTED`	Device does not meet engine requirements	`isDeviceSupported()` returned false previously; upgrade to the minimum requirement

Runtime (-2xxx)

Code	Meaning
`-2000 ERR_SESSION_DESTROYED`	Any method call on a session that was not closed; create a new session first
`-2002 ERR_CODE_DIR_NOT_FOUND`	Content directory does not exist — content deployment problem
`-2003 ERR_ENTRY_NOT_FOUND`	Entry file is not inside `contentDir`
`-2004 ERR_JS_EXECUTION`	Content JS threw an error; decode the JS stack from logcat
`-2005 ERR_CLEANUP_FAILED`	Terminal-state resource cleanup was incomplete — logcat will contain an earlier native cause; fix that, do not swallow this code

Platform layer (-5xxx)

-5004 ERR_INVALID_ACTIVITY — Activity is null or finishing; appearing during startup does not necessarily indicate a crash.

Engine-side positive codes (native may call your onError)

Native pushes these via the onError callback with a structured code:

Code	What it means
`203 NATIVE_OUT_OF_MEMORY`	V8 heap OOM: fired by the near-heap-limit callback; the isolate is terminated to prevent further damage
`204 NATIVE_JS_EXECUTION_TIMEOUT`	A single JS execution exceeded the watchdog timeout and was forcibly terminated
`205 NATIVE_HOST_PANIC`	Host thread encountered an unrecoverable panic — `isRecoverable` returns false; the host should treat this as non-recoverable (show error page, capture logs)
`206 NATIVE_ANR`	ANR detected at the native level, earlier than the system ANR
`207 NATIVE_CODE_SIGNATURE_INVALID`	Code signature verification failed — remember the pubkey chain in RuntimeConfig
`208 NATIVE_CODE_INTEGRITY_FAILED`	Code integrity verification failed — same as above
`11 NATIVE_INPUT_SATURATED`	Input event injection rate into the transport exceeds the consumption rate; events are dropped and the transport enters backoff

These positive codes are structured events: what onError delivers is not “the system crashed” but “the engine encountered this specific problem in this call frame” — the reproduction path is always traceable. Whether recovery is possible is determined by MigoException.isRecoverable().

MigoException: what `recoverable` actually means

session.setListener(new GameSessionListener() {
    @Override
    public void onError(MigoException e) {
        if (!e.isRecoverable()) {
            showErrorDialog(e.getMessage());   // full-screen error page; keep the log and the state
        } else {
            Log.w(TAG, e.toString());          // trace it, but raise no alarm
        }
    }
});

The per-code isRecoverable() determination is in the isRecoverable branch of ErrorCode.java: NATIVE_JS_EXECUTION_TIMEOUT and NATIVE_INPUT_SATURATED are both recoverable (the watchdog isolate can be restarted; the input transport recovers after backoff) — all others default to non-recoverable and must be treated accordingly on the deployment side: show an error page, do not swallow.

Diagnostic toolkit

Tool	What it gives you
`MigoRuntime.getNativeLoadError()`	The only first-hand answer for `-1003`
`session.setDebugEnabled(true)`	Live JS console output via ConsoleLogView / DebugOverlay
DebugOverlay	Frame rate and handle state (disable in production builds)

Error messages are not transcribed from documentation — the getErrorMessage branch in ErrorCode.java is the authoritative source for the table above; when you find a discrepancy, the source file is the final truth.