Shell apps
Troubleshooting
Fix the most common problems when building and publishing a Shell app.
The app doesn't load
| Problem | Likely cause | What to do |
|---|---|---|
| The Shell says the app can't be found | The address uses the wrong slug | Open /apps/<app-slug> with the slug shown on the app's page in the Client Portal |
| The Shell shows the app but no content | Nothing has been published yet | Run npm run release and gf apps publish --path release.zip, then check the app's Releases tab |
| The Shell shows an error where the app should be | appId in groundfloor.manifest.json and APP_ID in src/appIdentity.ts don't match the slug | Make all three the same, then publish again |
| The app crashes as soon as it opens | The app is wrapped in its own BrowserRouter | Remove it. The Shell already provides the router |
| Publishing works, but the old version still shows | The browser cached the previous release | Reload the page without the cache |
gf apps publish rejects the file | It isn't the release.zip from npm run release | Publish release.zip, not a ZIP of the dist folder |
Navigation and styles
| Problem | Likely cause | What to do |
|---|---|---|
| Links take users out of the app | Links start with /, such as to="/records" | Use useAppPath("records"). See Manifest and routes |
| A page is missing from the navigation | It has no route in the manifest, or the route has "hidden": true | Add or unhide the route, then publish again |
| Your app changes how the Shell looks | Tailwind's base reset is on, or another framework's CSS is loaded globally | Keep preflight: false; load other frameworks with FederatedStyleRoot. See Styling |
| Inputs and buttons have no borders | CSS after @tailwind utilities overrides the kit's reset | Put your own rules in a Tailwind layer, before the utilities |
Data, files and flags
| Problem | Likely cause | What to do |
|---|---|---|
401 | The user isn't signed in, or the token expired | Get a fresh token with __GF_GET_ACCESS_TOKEN__() before each request. Locally, run gf login again |
403 on data | The user's role has no access to that collection | Grant it in Data → Data Vault → the collection's Access. See Data |
403 on everything | The user signed in but has no role in your site | Give them a role on the Users tab of App authentication |
404 on a collection | The collection name is wrong, or it doesn't exist in this workspace | Check the name in Data Vault |
| A file upload never appears | The upload wasn't confirmed | Call …/files/{file_id}/finalize after sending the file. See Files |
| A flag change doesn't show | The hooks check every 60 seconds, or the app reads another environment | Wait a minute; check which environment the app is bound to |
| It works locally but not on the Shell site | Locally you act as a team member; on the site, as an app user | Grant the app user's role access. See Local development |
Still stuck? Check your release on the app's page in the Client Portal, and the Coderunner logs if your app calls a backend.