#Troubleshooting

#The Package Cannot Be Installed

Confirm the dependency name is exactly @theaiplatform/miniapp-sdk and your package manager is using the public npm registry for that scope. Remove any stale scope override left by an older private package setup.

Use a clean directory to distinguish registry access from project configuration:

mkdir sdk-install-check
cd sdk-install-check
pnpm init
pnpm add @theaiplatform/miniapp-sdk

#The SDK Reports an Unsupported Environment

Code read a live sdk property in a normal web page, build-time script, or unit test before a host capability session existed. Keep host access inside a target evaluated by The AI Platform, and pass a typed capability port to code that also runs in tests or during static generation.

#Publication Does Not Return an Immutable Root

Stop before importing the result into TAP Marketplace. Confirm that the publisher uses the generic tap-app build target and returns an exact https://<route>-ze.zephyrcloudapp.dev/ or https://<route>-ze.zephyrcloudapp.app/ root.

Dashboard URLs, tags, environments, version selectors, and build metadata are not installation inputs.

#Authentication Fails During Publication

Complete the deployment provider's supported sign-in flow or provide its CI credential through the deployment environment. Do not copy a private sign-in link into chat, an issue, or a build artifact.

Provider authentication is used only to publish ordinary assets. It does not grant TAP package, Marketplace, trust, acquisition, or installation authority.

#The Remote Entry Has the Wrong Type

All related Module Federation packages must use exact compatible versions, and the remote library must use type: 'module'. Inspect the emitted Federation manifest rather than assuming a successful compiler exit proves the remote shape.

For the current baseline, use exact 2.8.1 versions consistently.

#A Linked Local Package Does Not Refresh

Run the project developer command and confirm that it reports a generation-ready output:

pnpm exec tap-miniapp dev --once --json

The command requires an exact packageManager field, a build:miniapp script, and a relative tapMiniapp.output directory in package.json. Link that output directory, not a target staging directory such as .tap-build/desktop unless it is also the assembled package output.

The AI Platform watches linked directories automatically. If the status is Path unavailable, restore or relocate the mapped directory. If it is Failed, fix the reported build or activation error; the previous active generation remains available.

#A Local Change Requires Review

Permission removals and narrower authority activate automatically. A new action, broader actor or scope, higher autonomy, less restrictive consent, or any incomparable authority change requires review. Local service contribution changes always require review.

Review the exact candidate contract in Miniapps settings. Do not remove and re-add the local source to bypass the review, because doing so discards the failure context without making the requested authority safer.

#A Local Service Does Not Start

On desktop, open Apps > Marketplace > Installed. On mobile, open Workspace Settings > Miniapps > Installed. Select the package and inspect its Local services panel. Choose View local logs before restarting. The log tail is bounded, remains on the device, and belongs only to the latest service generation.

#The platform is unsupported

local_service.unsupported_platform means the signed descriptor has no launcher for the current desktop target. Baguette v0.1.85 supports only aarch64-apple-darwin. It does not run on Intel macOS, Linux, Windows, or mobile.

Use a supported machine or publish a new release containing a complete launcher and locked runtime for that target. A miniapp cannot supply a fallback executable or change the launcher at runtime.

#Permission was denied

local_service.permission_denied means the device user has not approved local-service.run and the exact service effect for this release. The package can remain installed while its service is unavailable.

Review the package in Miniapps settings and approve only if the service name, supported platform, sandbox profile, and release are expected. Every new release that contains a local service requires fresh device-user review. Reinstalling does not make the requested authority safer and can hide the original failure.

An Untrusted local-directory package cannot run a production service. Exercise it in a reviewed Live TAP Test Lab profile with nativeServices: true, action:local-service.run, and the exact service effect.

#Xcode or CoreSimulator is unavailable

The Baguette launcher uses the closed apple-simulator-control sandbox profile. It requires Apple Silicon macOS 15, the full Xcode application in a supported location under /Applications, the iPhone Simulator platform, and at least one installed simulator device.

Run these checks:

uname -m
sw_vers -productVersion
xcode-select --print-path
xcrun simctl list devices available

If xcode-select points to Command Line Tools or a custom Xcode location, select the supported application bundle, for example:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Open Xcode and install an iOS simulator runtime if simctl lists no available devices. Then retry ensureRunning. A missing or unreviewed Xcode capability can surface as local_service.sandbox_unavailable.

#Readiness times out

local_service.readiness_timeout means the process did not return a successful response from its signed readiness path before the deadline. For Baguette, the path is /simulators.json and the deadline is 30 seconds.

Inspect View local logs for Xcode, CoreSimulator, bind, or startup failures. Confirm the package contains the complete Baguette bundle and that the manifest uses the host placeholders for --host, --port, and --allowed-hosts. Fix the package source and publish a new immutable release. Do not increase authority or add runtime-supplied arguments to hide a packaging error.

#The service enters a crash loop

local_service.crash_loop means the service exhausted its signed restart budget. For the Baguette example, that budget is three restart attempts within 60 seconds with a one-second backoff.

Read the local log tail and fix the external prerequisite or package defect. After the cause is resolved, choose Restart and confirm that current miniapp connections may be interrupted. Restart clears the restart window, re-verifies and rematerializes the active release, and creates a new generation. There is no miniapp-facing Stop, Kill, PID, port, or process control.

Treat an unknown local_service.* code from a newer host as an ordinary operation failure. Preserve the code in user-visible diagnostics and avoid exhaustive handling that would turn a future code into an application crash.

#The Descriptor Does Not Validate

Open manifest.tap.json with the published config-schema.json assigned through $schema. Common failures include:

• a missing package, release, presentation, compatibility, target, or contribution field;
• a contribution selecting an undeclared target or expose;
• an invalid runtime for the selected target;
• a permission action referenced but not declared; or
• an unknown property in an object that rejects additional properties.

Validate the emitted descriptor too. Source pending integrity values must be replaced by the build.

#Content Security Policy Blocks an Asset

Keep runtime files inside the package target graph and resolve them with resolvePackageAssetUrl. External network, frame, worker, media, and font access remains subject to the package policy and host authorization.

Do not add broad script permissions to work around an incorrect asset path. Inline executable script and dynamic code evaluation are not portable defaults.

#Integrity Verification Fails

Rebuild every target from a clean staging directory and assemble once. Do not modify dist after assembly. Verify that the publisher uploads bytes from the assembled directory and preserves their paths exactly.

A changed remote entry, Federation manifest, async chunk, stylesheet, presentation asset, or lock file changes the final identity.

#A New Release Does Not Activate

Check the activation error shown for the installation. The host can reject a candidate for compatibility, integrity, import, mount, authority, or state-restoration failures.

The last known good release should remain active. Fix and publish a new immutable release, or explicitly restore a previously verified TAP release. Do not overwrite the failed release.

#A New Zephyr Deployment Does Not Update Existing Installations

This is expected. The AI Platform does not follow provider tags or environments and does not poll for deployment changes.

Import the new deployment as a new exact TAP Marketplace release, then explicitly update the publication or workspace assignment.