Help and troubleshooting · cApp Developer Docs

Find the failing boundary first

Before rebuilding or resetting anything, identify where the problem occurs: public documentation/preview, browser workspace, compiled preview, installed app, local service, product backend, wallet or external provider. The same-looking page can have different authority in those environments.

Record the exact user action, application/component version, target and observed error. Stop repeated write/send actions when an outcome is uncertain. Preserve local records and backups; do not start by uninstalling, clearing site data, generating a replacement wallet or disabling security checks.

First question	Check next
Is this the public website?	Documentation and hosted Lab previews are read-only; owner tools and wallet execution are not expected there.
Is the capability missing or merely not ready?	Selection, declared target, actual installed package, owner surface and status.
Did compilation finish but packaging not run?	The immutable release and platform output are separate artifacts.
Is a local helper or product backend unreachable?	Inspect the installed service connection and backend origin separately.
Could the action already have happened?	Read/reconcile the saved operation before attempting any replacement.
Is only the displayed evidence incomplete?	Preserve the observed outcome and any local tracking error as separate facts.

Sidecar unavailable

Check that it is selected for this application, supported on the target and present in the package actually installed. Match the component version to the changelog; a declaration of a target is not a successful installed-device test. A planned component has no runtime to discover.

Resolve APIs from the owning app surface, not a remote Links tab. Await supported readiness and inspect its result; neither a method name nor a manifest capability automatically creates a provider or grants Agent authority. The portable Solana client does not start providers.

Keep missing selection, failed initialization, wrong provider mode and missing permission distinguishable. Do not create a replacement with application defaults to hide a selected component's failure. See Library, Build with Sidecars and the component reference.

Compile succeeded but there is no installer

Compile produces an immutable compiler release; Windows/Android packaging is a separate action. In Build, select the intended release and inspect Output for the actual target artifact and build result. A packaged preview/diagnostic shell is not proof that the source application works.

Source changes need a new compile release. Target packaging/signing changes can require repackaging the intended release. Reusing an old immutable release deliberately reuses its old content. Agent and Build input settings must be checked rather than assumed identical. See Compile, package and release and Runtime environments.

Installed app cannot reach a service

Inspect the installed service bridge and the relevant component's health/logs. Do not hard-code a development port to make an installed diagnostic pass. A helper that happens to run beside the development checkout is not proof that the installed package owns its required service.

Check the application backend separately from cApp's local services and from Solana RPC. A login page opening does not prove the product backend session is established. On Android, loopback belongs to the device/emulator; an endpoint working in your desktop browser may not be reachable there.

Use Service Inspector where supported, Debug Inspector and the server integration guide. Record status/error and a bounded log excerpt, not the entire environment or an unredacted request dump.

Local AI is unavailable or slow

Confirm package selection and engine readiness, then check that a compatible model is actually loaded. The engine package is not the GGUF model. A successful download, detected GPU or recommended settings profile does not prove the subsequent completion used that processor.

Try one small completion through the owning Studio, then the scoped application connection. Check input/context/output limits and competing work. There is one active generation; opening another connection does not reserve another engine. Keep controls guarded until the original request settles after Stop.

Authored Guide steps and help browsing do not necessarily require a model. A model reply does not prove that a workflow or tool action ran. See Local AI, Guide and Working with Agent.

Payment returned an error or stopped responding

Distinguish preflight rejection, declined approval, uncertain authority, uncertain submission and incomplete observation. Preserve the operation, attempt, sender and signature. A response can disappear after a provider accepts the transaction; a local tracking write can fail after confirmation.

Use Recovery and receipts to observe the same operation. Do not generate another ID, replace the payer, extend request expiry or resend a whole payout batch to fix one unresolved item. A merchant must verify recipient credit independently; a receipt pasted into a support conversation is not its fulfilment authority.

For OFFLINE, 401/403, 429, wrong-genesis or adapter errors, use Provider configuration. Fix the owner connection, not the transaction's intended network. Never post a token or full credential-bearing endpoint while reporting the error.

Market data is absent or stale

Inspect the selected provider, enabled state, instrument ID, budget and cooldown. Check quote.available and quote.stale; an old numeric value is not a current executable price. A listener may not fire when time alone makes a quote stale, so the display must re-evaluate age without starting a new provider per view.

Sampled candles are not a historical exchange trade feed, and missing volume must remain missing. Dispose only the current view's listener/demand; do not shut down a shared provider used by another feature. A missing selected Market Pulse instance must not become an enabled fallback. See Market Pulse.

Android update will not install

Check package ID, signing identity, version and architecture against the selected device and artifact. Confirm that an AAB has been converted/installed through the supported workflow; it is not the same artifact as a directly installable APK.

A signing mismatch, stale artifact or wrong ABI is not a reason to uninstall automatically. Prefer a compatible data-preserving update using the intended key/version. Preserve independent wallet backups and unresolved operation evidence before any destructive change; receipt exports do not back up keys or models.

After installation, launch and test that actual package. A docs/site publication does not update native runtimes already on a device. See Android deployment for the build/install/run workflow and diagnostics.

Other common integration symptoms

Symptom	Check and next step
Sign-in window closed but account still anonymous	Refresh account state through the existing product session path. Window opening/closing and local logout are not proof of a server session change.
Link requested but page blank or refused	Inspect target URL, selected navigation policy, remote response/frame restrictions and native/browser environment. Do not automatically launch a second destination after an uncertain result.
Local record saved but backend unchanged	Inspect read-back metadata, server revision, pending/conflict state and actual acknowledgement. Local storage is not synchronized delivery.
Agent reply says work is complete	Check operation receipts, actual artifacts and saved state, not the model's prose. Scope and approval still apply.
Test script passes without the expected product state	Assert an observable value on a stable registered target. A screenshot or selector existing is not the whole business outcome.
Studio edit disappeared or an old version is packaged	Check scope, autosaved draft, immutable published version and selected release. Closing Studio is not a general discard action.
A public download or nested docs link is missing	Record the exact public URL and status, then check the published version. Never substitute an owner-only route or internal source dump.

Report a useful issue

Use this short template. Replace identifiers with consistently labelled placeholders where they identify private customers or source; include a real public-chain signature only when relevant and knowingly shared. Keep a minimal reproducer separate from a full project export.

Title: The specific action and visible failure
Environment: Public preview / browser workspace / installed Windows / installed Android
Application and component versions:
Expected result:
Steps: 1. ... 2. ... 3. ...
Observed result and bounded error code:
Artifact or operation identity: Redacted when sensitive; retained privately for correlation
External effect: Definitely not started / potentially started / observed result / unknown
Recovery tried: Read-only checks and their results
Attachments: Minimal sample data and reviewed, bounded diagnostics only

Review exports before sharing. Remove provider credentials, authentication headers/cookies, wallet keys/backups/passwords, signed transaction bytes, private source, customer data, prompt/knowledge content and credential-bearing URLs. Automated redaction is not a guarantee. Keep exact raw evidence privately when it is needed for recovery.

For a suspected exposed credential, stop publishing it and use an established private maintainer/provider contact to arrange revocation and replacement. Do not include the credential in a public issue. This page does not invent a monitored security inbox or guarantee a response channel that the project has not published.

The changelog records public component notes and clearly labelled documentation baselines, not the internal task queue. Updating the docs can explain a known limitation without fixing an installed runtime.