Apps keep your feasibility numbers, reports, and site tools close at hand. When one won't add, save, or load, find the message you see below for the cause and the fix.

Learn how to add an app or browse the App Library.

Problems with apps

I can't find an app

Each app opens in one panel at a time. If you can't see an app, it may be open in another panel.

Click Add tab in the panel where you want the app.
Search for the app in Add an app.
If the app is already open, choose Move here to bring it to this panel, or Focus to jump to where it is.

If the search shows "No apps found," the app may not work where you are. See the next section.

An app isn't available in a Space

Some apps only work in a project, and some only work in a Space. Add an app only lists the apps that work where you are. Open a project to use a project-only app.

An app shows "Something went wrong" instead of loading

Click Reload in the panel to restart the app. A box titled "[app name] error" with the message "Something went wrong in [app name]." means that one app hit an error.

The rest of Giraffe keeps working, and the other panels aren't affected.

If the error comes back after you click Reload, try these in order:

Refresh the browser tab.
Remove the app and add it again. Right-click the app's tab, choose Remove app, and confirm. Then click Add tab and add the app back from Add an app.
If the error still happens, contact support. Include the project link, the app's name, and what you were doing in the app when the error appeared.

🚨 Warning: Removing an app takes it out of the project for everyone, not only you.

If a panel shows "Cannot Load Content," a new version of Giraffe may be out. Save your work, then click Refresh Giraffe.

I can't add an app

You need Edit or Admin access to add apps to a project. In a view-only project, adding an app does nothing. Ask the project owner for edit access.

If you add an app the project already has, Giraffe keeps the one that's there.

Giraffe warns that an app is third-party software

Giraffe shows "Warning: this app is third-party software and may not be secure" when you add an app that Giraffe doesn't recognize. The app is still added. Keep it only if you trust the people who built it.

An app needs a credential to connect

Some apps connect to outside services with a key or password. A workspace admin stores these as credentials and shares them with the apps that need them.

In workspace admin, open Credentials.
Click New credential and fill in Name, Description, and Credential value.
Share the credential with the app.

If an app can't connect, ask a workspace admin to check that the credential exists and is shared with that app.

Problems building apps with the SDK

The Giraffe SDK lets your team build apps that run inside a Giraffe panel and read or change project data. These sections cover the questions developers ask most.

Read the SDK docs, or start with Get Set Up with the SDK.

My app panel says "localhost refused to connect"

The app is pointing at a development server on your own computer, and that server isn't running.

If you didn't build an app, change the app's URL to a real web address, or remove the app from the panel.
If you're developing, start your dev server on the same computer as your browser, then reload the panel.

If your browser blocks the connection with a message about your local network, allow the local network request in your browser's site settings, or host the app at a public URL.

Register an app for my workspace

Registering an app makes it available to add from Add an app. It needs an Enterprise plan.

In workspace admin, open Apps.
Click New App.
Fill in Name, URL, and Logo URL. The URL must be a full web address, like https://example.com/app.
Optionally, set a Default Configuration. Put shared settings under Public and secrets, like API keys, under Private.
Click Create App.

To change the URL later, open the app in Apps and edit it in Edit App.

My app shows a blank panel

Check these, in order:

The URL points at your built app, not your source code. Serve the built files.
Your server allows Giraffe to embed the page. Remove an X-Frame-Options header or a frame-ancestors rule that blocks it.
Your company network doesn't block the app's web address.
Apps hosted by Giraffe can't use cookies or local storage. Store data with the SDK instead.

My app doesn't get any project data

The SDK only sends project data to apps running inside Giraffe, or on localhost while you develop. Open the app inside a Giraffe panel, not in its own browser tab.

Giraffe asks permission when my app makes changes

Giraffe asks before an app it doesn't recognize changes a project or reads a full project. Click to allow it if you trust the app. Apps hosted on giraffe.build don't ask. Apps Giraffe doesn't recognize also can't create projects in bulk.

My app hits a limit

The SDK limits how often and how much an app can do:

Action	Limit
Create a project	10 per minute
Create projects in bulk	100 per call, Giraffe-hosted apps only
Project bundle	500,000 characters
Workspace details	200,000 characters
Save user data	One call every 10 seconds, up to 5,000 characters per app and 20,000 in total
Panels per app	8

I can't add the IFrame app or open the JSON editor

The IFrame app and the JSON editor need a Team or Enterprise plan. On Core, they're grayed out or ask you to upgrade. Ask your workspace admin about upgrading.

Error messages

Giraffe shows these errors in toasts at the bottom of the screen when something with an app fails.

Error	What triggers it	What to do
"Failed to create app: [(server error text)]"	Creating an app failed.	Try again.
"Failed to update the project for this app. If this problem persists, please contact support."	Changing the project's settings for an app (for example usages or analytics) failed to save.	Try again, or contact support.

Other app messages

These toasts confirm that something worked, or ask you to fix a small thing before you continue.

Message	What triggers it	What to do
"[app name] is already added to project"	You tried to add an app that is already in the project.	None
"Added [app names] to this project."	You applied a layout that uses apps, and those apps were added.	None
"Could not open Precinct in external window. Have you blocked popups?"	Precinct could not open in a separate window.	Allow popups for this site.
"Drop an HTML file / Drop a file, not a link"	You dropped a file that is not HTML, or dropped a link, onto the app HTML upload box.	Drop an HTML file.
"Invalid JSON for [app name]"	You saved text in the JSON editor that is not valid JSON.	Fix the JSON and save again.
"Invalid JSON in [field name]"	You entered invalid JSON in the create app form on My Apps.	Fix the JSON.
"saved"	You saved your changes in the JSON editor (Advanced menu, team and enterprise plans).	None
"Warning: this app is third-party software and may not be secure. Make sure you trust the authors."	You added an app made by a third party.	Only keep apps from authors you trust.

Troubleshoot Apps