#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 Uses the Wrong Zephyr Environment

Stop the publication before retrying. Review the selected Zephyr account, organization, project, application, and environment in your build configuration. Print only non-secret identifiers; never print credentials or an authentication URL.

After publishing, verify the immutable release first and then verify that the intended logical tag and environment resolve to it. Build metadata alone is not proof that a tag changed.

#Authentication Fails During Publication

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

If a cached session belongs to another Zephyr environment or account, sign out through the supported client and authenticate again.

#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.0 versions consistently.

#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 move the development tag back to a verified release. Do not overwrite the failed release.

#Followed Updates Do Not Appear

Confirm that the installation follows the intended environment, the environment resolves through the expected tag, and the tag resolves to the new immutable release. Also confirm Follow updates remains enabled in Miniapps settings.

If the selector is correct, inspect the last update check and activation error before reinstalling. Reinstallation can hide the update failure you need to diagnose.