Skip to main content

Start with the failing stage

Check the stages in order: project setup, build, package registration, screen placement, capability approval, Portal publication, widget rendering, then data access. A working Droplet receiver does not prove that a widget exists in the company catalog or on a published Portal screen. Follow the company quickstart for the complete flow. Record the Portal URL, widget name, package ID and version, whether you are testing a draft or published Portal, and the exact error. Keep credentials, session proofs, signed payloads and member data out of screenshots and diagnostic reports.

The agent cannot build or find the widget project

Open the Portal project as the agent’s working project, rather than running Portal commands from the Droplet backend folder. Check the project’s package manager and lockfile before installing dependencies. If the agent cannot access that project or run the install, complete that specific setup step before asking it to continue; creating a remote Portal app does not fix local file access.

A required SDK is missing or dependencies disagree

Check the receiver and widget projects separately. The receiver needs its server-side @fluid-app/droplet-sdk dependency; the Portal project needs @fluid-app/portal-sdk. A dependency added to one project does not install it in the other. Verify both the dependency declaration and the installed module before building. Do not write a substitute signature verifier to work around a missing SDK. Use the package manager selected by the project and its lockfile. If dependencies were installed with another manager, reconcile the installation before continuing. If Mist cannot run that install, give the user the exact project folder and required command, then recheck the installed dependency. Do not repeatedly claim the install is complete based only on an edited package.json.

The published SDK lacks the required function

Check the installed worker entry and published SDK reference for queryDropletData. A source merge, version guess or unrelated SDK release does not prove that export is available. Verify the receiver SDK independently; the two SDKs have different versions. Upgrade through the project’s normal dependency workflow when a supported release is available. If it is not available, report the missing release; do not invent a worker fetch or host bridge.

The package has the wrong owner

Use the generated project for the intended model. Company packages belong in portal projects. Standalone packages use Droplet ownership and fluid.widget.config.ts. Do not copy configuration between models. Confirm ownership from the authorized company and installation records, not a hostname or display label. A Droplet receiver deployment does not change company ownership. Do not create duplicate installations or change ownership to make a test pass. A draft label or presentation active: false alone does not establish whether owner-company testing is available; check the installation and an actual authorized query. See Droplet availability.

A package identity is already in use

Keep the scaffold’s package identity consistent. If initial registration conflicts with another package, choose a distinct company package identity rather than overwriting the other package. After publication, treat an identity change as a different package; existing screen placements and approvals do not automatically transfer.

A standalone project has no Droplet ID

The explicit ID avoids an interactive lookup. Confirm that the Droplet already exists and that your credentials can access it.

A portal function is rejected as undeclared

Import the typed function from @fluid-app/portal-sdk/widgets/worker, add that same function value to the widget’s uses, rebuild, and retry.

Defaults fail validation

Compare defaultProps and field defaults with the current property schema. Keep JSON values within the worker-safe SDK types. Test missing and malformed persisted inputs separately.

Styles are missing

Restore the generated root styles.css. Preserve the standalone template’s guarded worker import. Company widget modules must not import CSS directly.

Build fails after stale generated output

Preserve author source and configuration. Remove only generated .fluid/widget-build/, .fluid/tmp/, or .fluid/widget-dist/ content, then rerun the failed command.

A published version already exists

Published Widget Package versions are immutable. Increment the semantic version and publish again.

Push and publication disagree

fluid widget push separates repository synchronization from publication. Read the phase result and inspect fluid widget status and fluid widget logs before retrying.

Network approval is rejected

Confirm that the widget declares networkAccess, the package has been reviewed, and the approval matches the exact package ID, package version, and capability version. --yes alone does not approve it.

The widget is absent from the catalog or live screen

Confirm package publication succeeded for the intended company and exact package version. Then check the builder separately: was the widget placed, approved and saved? Was the intended Portal version published? fluid portal deploy publishes company widget artifacts; it does not activate a Portal version. Do not republish an unchanged package to solve an unsaved screen placement.

An updated widget has stale capability approval

A placement approved for package 0.1.0 is not approval for package 0.1.1, even when the widget name and requested capability are unchanged. The host can reject the call before any network request occurs. Check the exact package ID, package version and capability version for every affected placement. In the builder, select the widget. Its settings say its capabilities are blocked and show a Review capabilities button. Click it, review Allow capabilities, then save and publish the intended Portal changes when authorized. Do not copy grants between widgets or edit permission JSON. See Portal Droplet data.

The widget says unable to render or disappears

Read the first widget-specific console error before investigating data access. A worker startup or stylesheet failure can prevent rendering before a Droplet query is sent. Check both the widget artifacts and the Portal host deployment; upgrading one does not prove the other is current. For Remote DOM widget styles failed to load, inspect the failing stylesheet request. Check its URL, response, content type and browser error. If the widget stylesheet loads successfully, the failure may concern host-provided styles instead. Capture the failing asset URL and Portal build information for Fluid support. Do not remove styles, weaken browser security or republish unchanged widget code to hide a host loading failure. A worker startup error mentioning an invalid custom-element name can indicate an incompatible SDK/runtime combination. Record the exact error and installed package versions, and use a supported SDK release containing the runtime correction. Rebuild and publish a new immutable widget version when its bundled runtime changes; then approve that version in the builder. Do not rename generated runtime internals or weaken sandbox checks as a workaround.

The receiver URL returns not found

Confirm the route is included in the completed receiver deployment and that the registered data_url points to that deployment’s intended stable URL. A ready initial deployment may still contain the old code. A not-found response does not verify signature rejection. Test the deployed receiver, then test an authorized call from the widget; follow the receiver guide for verification.

Member data is unavailable

The builder names the cause when it can: an unsupported capability version, missing approval for this exact package version, or a builder preview that can’t reach portal capabilities. Test approved widgets in the signed-in Portal. If the cause still isn’t clear, check these in order:
  1. Confirm the installed SDK exports queryDropletData and the deployed Portal host supports the capability. Check the widget declares that same function in uses.
  2. Verify the current placement’s exact package-version approval. Missing or stale approval can block the call before HTTP.
  3. Test the actual signed-in Portal, with the page focused. Preview or an unavailable session can prevent private reads. Refocus and reload for a clean test; do not bypass session checks.
  4. Confirm the target company actively installed the intended Droplet and that its canonical data_url points to the deployed receiver.
  5. Match the operation and response validator to the receiver’s real contract. member.echo and member.whoami are different application-defined operations; neither is a universal Fluid operation.
  6. Check the actual widget’s host call and receiver result. An unsigned request being rejected proves signature enforcement, not that an authorized widget call succeeds. A successful separate API test does not prove widget approval or rendering.
Use Portal Droplet data for receiver setup and supported calls. If diagnostics expose a portal function error, record its code and safe message without logging private response bodies. Do not fall back to worker fetch, another member identity, fabricated data or a custom bridge.

Console errors mention unrelated content

Match each error to its request and widget. A missing media item on the same screen is not by itself evidence of a Droplet query failure. Diagnose the stylesheet, capability and data call separately; do not change unrelated content to make the console quiet.

What an AI agent should report

State the failing stage, exact package version, safe error, checks actually performed and next action. Distinguish local build success, package publication and a real Portal UI test. If builder access or permission approval is unavailable, report that prerequisite instead of claiming completion or inventing another approval mechanism.