Authentication fails
Confirm the Fluid CLI login or API token and the selected environment. Correct the credentials, then rerun only the failed remote command.Pull selects the wrong definition
Use the definition ID to avoid duplicate-name ambiguity:--force unless overwriting local changes is intentional.
Preview omits a resource
Preview skips a file that isn’t valid JSON without printing a warning, so check the file you edited last. Validate it against its$schema, then restart the preview. An unresolved navigation entry can remain visible without loading its target screen.
The portal shows the wrong menu or none of your screens
Locally, check that you edited the profile marked as default: preview shows only that one. On the deployed portal, check that the viewer matches the profile’s rules, that the profile’s navigation points to the screen, and that you created and activated a version after pushing. A viewer who matches no profile falls back to the default profile without an error. See How the portal picks a profile.Authenticated screens return 401 locally
Localhost does not receive production member authentication. Confirm the Portal Definition with public or non-authenticated routes locally, then test authenticated behavior in the appropriate hosted environment.Push rejects a reference
Compare every referenced slug with its resource file name. Fix missing screens, navigations, profiles, or themes and validate again.Pull or clone warns that a file doesn’t match the schema
fluid portal pull and fluid portal clone still write a definition whose files don’t all match the schema. They correct some older formats on the way in. Any other file is written as Fluid serves it, with a warning that names the file and field. Push still refuses a file that fails validation, so fix the named files before you push.
Push stops after some changes
Push can partially succeed. Read the command result, inspect remote state, correct the reported resource, and rerun. Do not assume earlier changes rolled back.Remote state changed during local work
Preserve local edits, pull current state, reapply the intended change, and review the new diff. Do not hand-edit.portal-sync/.