Troubleshooting

Start with apexrest status --detail doctor --json (or apexrest_status with detail: "doctor" in the conversation), then use the reported capability or fault code. A detected executable, a validated compiler, plugin discovery in the host and a working database connection are separate states. Every failed result carries nextActions; follow them before retrying.

The apexrest command is missing

apexrest setup (managed installation) and npm install -g apexrest create the apexrest command; codex plugin add, claude plugin install and installing tools alone do not. Follow the launcher instructions, or run the bundled runtime from a checkout:

node plugins/apexrest-apex/runtime/apexrest.mjs --help

apexrest without arguments prints help. Use the current source bundle and run npm run plugin:sync after changing runtime source. If managed plugin files were removed, their launcher has no runtime to start; install again from a checkout or npm.

Saved connections are missing or fail their test

connection add --sqlcl-name NAME records an APEXREST reference; it does not create a connection in SQLcl. Save the connection interactively in SQLcl, then apexrest connection list --saved --json reads that store and apexrest connection test NAME --saved --json tests the exact saved name, including case and spaces. ORDS references are tested with apexrest connection test REF --json after sqlcl configure --database-transport ords.

Check APEXREST_SQLCL, APEXREST_JAVA_HOME and APEXREST_HOME if tools were installed elsewhere. Repair missing or expired credentials in SQLcl; a successful doctor run does not establish database connectivity.

The plugin is installed but tools are missing

Start a new session after installing or updating the plugin; hosts cache the skill and tool catalog. Check that the plugin is listed and enabled in the same profile: codex plugin list --json, or claude plugin list. The MCP server is node <plugin-root>/runtime/mcp.mjs, started by the host from the installed plugin directory with no downloads; do not add a second global MCP server to conceal a failed installation. In Claude Code, claude plugin validate --strict <plugin-root> checks the manifest and /mcp shows whether the apexrest server started. The server exits with APEXREST requires Node.js 24 or newer. when the node on the PATH of the shell that started claude is older (for example an older nvm default); switch Node before starting claude. Plugin MCP servers inherit that shell's environment, so export APEXREST_HOME there when you use a custom managed home.

Project-scoped tools reject a missing or relative project argument: pass the absolute directory that contains apexrest.json, never the plugin directory. No folder trust list is required; host filesystem permissions govern project access.

SQLcl is present but compilation fails

Select the compiler for the source profile: SQLcl 26.1.2.132.1334 for the reviewed 26.1 workflow, or 26.3.0.260.1620 with MMD 26.2.0+3479 for 26.2 partial imports. The managed Java baseline is 21; APEXREST_JAVA_HOME selects an existing compatible runtime. apexrest_apex_validate returns structured diagnostics (file, line, column, type, message, validValues, hint): repair the named file and line and rerun. SQLcl can print an error and still exit zero, so validation requires a success marker and no error indication; otherwise it reports VALIDATION_UNCONFIRMED with the compiler output.

Offline validation and help reuse a pooled SQLcl process. Generation on 26.3 is isolated to avoid a verified compiler-state issue; 26.1 retains its established pooling behavior. A timed-out, cancelled or failed command kills its session and the next call starts a fresh one; a session idle for ten minutes is reaped. If the pool itself cannot start (for example after replacing the SQLcl installation), restart the host session so the MCP server restarts.

Preserve Oracle-generated .apex/apexlang.json and component IDs. Never invent an MMD version or edit internal APEX tables to work around a compiler incompatibility. Use the references for the selected toolchain version and make a focused source correction.

Ship, target or policy checks fail

APEX 26.2 partial imports

The partial-import guide lists exclusions and the narrowly allowed readback transformations. OUTCOME_UNKNOWN still requires the recovery procedure below.

General deployment checks

Connection credentials belong in SQLcl's store or the private ORDS credential file. Do not put them in an issue or prompt. See configuration and the safety skill.

A job is still running, failed or has an unknown outcome

apexrest_ship returns a jobId when they exceed waitSeconds. Read apexrest_job action:status with that ID (waits up to 120 seconds and reports the phase: validating, planning, backing_up, migrating, importing, verifying, syncing); never rerun the operation to fetch its result. A completed job can still carry a failed operation result: read its diagnostics. A job whose worker never started is failed and needs a new job after the diagnostic is resolved.

OUTCOME_UNKNOWN, JOB_OUTCOME_UNKNOWN, an expired heartbeat or a lost import response mean the database may have changed. Do not blindly replay writes or clear ownership. Inspect the deployment state, journal, target history and APEXlang snapshot (or legacy SQL backup) with apexrest deploy status --project PROJECT --run RUN_ID. Use apexrest_ship mode:recover with the original run and user request for server-first readback; the runtime recognizes already-applied sources or safely replans remaining APEX metadata. Database-operation uncertainty and conflicts require explicit review before a retry. Cancellation never implies rollback. Restore has its own plan and exact approval and restores APEX metadata only. See deployment and recovery.

Browser verification or charts do not work

apexrest_browser_open returns the configured URL for the host in-app browser (host, legacy alias codex). Complete login in that browser and exercise the affected pages; opening a page is not verification. No external browser is launched and no saved authentication state or automatic application suite is used. If an old preference says external, change it to host or select browserMode:host for the call.

Wait for asynchronous APEX chart regions to finish loading before judging an empty chart. After a filter action, verify that the relevant page items were submitted and every affected region refreshed. A loading overlay or an old tab with a pending navigation may require a fresh page inspection before changing source. Record an unavailable browser or deployed change as missing verification with a reason, following the browser verification rule.

Offline, proxy or download errors

Preload the exact SHA-keyed vendor artifacts and client-tool archives. --offline never falls back to the network; a cache miss is a dependency blocker and a corrupt artifact fails integrity. Each download attempt fails after 60 seconds without new data and is retried up to three attempts in total. PROXY_UNSUPPORTED means a proxy is configured but the running Node cannot apply it: run with NODE_USE_ENV_PROXY=1 on Node 24 or later, or preload the offline cache. UNSAFE_CACHE_DIRECTORY means the download cache is not owned by the current user or is group/world writable.

Setup is locked or interrupted

Concurrent setup reports LOCKED. A proven dead process on the same host can be recovered through the dedicated recovery gate. Unknown ownership, another host or an interrupted recovery gate requires inspection; do not guess that a live lock is stale.

LOCK_CORRUPT reports a lock file without a readable owner that is older than 30 seconds, usually left by an interrupted process. Confirm that no apexrest operation is running on any host, then delete the lock file named in the message and retry. There is no automated recovery command for this case.

Native packages are copied through staging and atomic rename. A rerun probes completed components. Preserve unrelated plugins and the private managed state; deleting everything is not a normal repair step.

Report a reproducible problem

Include the plugin version, OS/architecture, host (Codex or Claude Code) and its version, exact sanitized command or tool call, fault code and the smallest source example that reproduces the issue. Distinguish local fixture results from Oracle or host observations. Review diagnostics for paths, credentials and business data before attaching them to an issue. Use private reporting guidance for sensitive findings.

View this page source