## Embedded app connection and authentication issues

URL: https://docs.atlan.com/product/capabilities/build-apps/troubleshooting/connection-and-authentication-issues

> Troubleshoot timeout, iframe loading, and 401 errors when your app is embedded in Atlan.

Use this guide when your embedded app shows "Failed to respond," doesn't load in the iframe, or returns 401 or token errors. Follow the solutions below to fix handshake, CSP, and token handling issues.

## App shows timeout or "failed to respond"

:::::danger Error
**Failed to respond**
:::::

### Cause

Your app doesn't complete initialization in time. This can happen if the app doesn't send the ready signal, or if startup code throws an error.

### Solution

1. Open the browser developer tools and check for errors in the **Console**.
2. Initialize authentication as early as possible in your app startup code.
3. If you implemented `postMessage` manually, send `IFRAME_READY` immediately after receiving `ATLAN_HANDSHAKE`.
4. Confirm `allowed_origins` includes your app origin (for example, `https://app.company.com`).

---

## Asset GUID is missing in profile tab

::::::danger Error
**Asset GUID is missing in profile tab**
::::::

### Cause

Atlan only sends an asset GUID when your app renders in the `asset-profile-tab` slot and the slot conditions match the current asset.

### Solution

1. Confirm the app is configured to render in the `asset-profile-tab` slot.
2. If the app uses conditional rendering, confirm `when.assetTypes` includes the asset type you are testing.
3. In your app, read the GUID from `context.page.params.id`.

---

## App can't be embedded in iframe

:::::danger Error
**Refused to display in a frame**
:::::

### Cause

Your app blocks iframe embedding through response headers, such as CSP `frame-ancestors` or `X-Frame-Options`.

### Solution

1. Add a CSP header that includes Atlan as a `frame-ancestors` origin:

 ```
 Content-Security-Policy: frame-ancestors 'self' https://*.atlan.com;
 ```

2. Remove or change `X-Frame-Options` if it blocks embedding. Values like `DENY` and `SAMEORIGIN` prevent Atlan from loading your app in an iframe.
3. Verify the header on your deployed URL:

 ```bash
 curl -I https://app.company.com | grep -i content-security-policy
 ```

---

## App doesn't receive messages from Atlan

### Cause

Your app ignores messages because the origin doesn't match, or messages are posted to the wrong target origin.

### Solution

1. Confirm your app validates the parent origin (your Atlan tenant), for example `https://your-tenant.atlan.com`.
2. Confirm you never use `'*'` as the `targetOrigin` when calling `postMessage`.
3. Confirm `allowed_origins` in your app registration matches your app's deployed origin.

---

## API calls fail with 401 or token errors

### Cause

Your app uses an expired token, doesn't refresh tokens, or keeps tokens after session end.

### Solution

1. Use the Atlan Auth SDK so token refresh and session changes are handled automatically.
2. If you implement `postMessage` manually, request a fresh token before expiry using `IFRAME_TOKEN_REQUEST`.
3. Clear cached tokens and session state when your app receives `ATLAN_LOGOUT`.

---

## See also

- [Embed your app](https://docs.atlan.com/llms/platform/build-apps/embed-in-atlan/llms.txt): Prepare your app for iframe embedding
- [Register your app](https://docs.atlan.com/llms/platform/build-apps/register-app/llms.txt): Confirm `iframe_url`, `allowed_origins`, and render slots
- [Send and receive messages](https://docs.atlan.com/llms/platform/build-apps/postmessage-reference/llms.txt): Message types and payload shapes
- [Embedded apps security FAQ](https://docs.atlan.com/llms/platform/build-apps/embedded-apps-security/llms.txt): Security considerations and token handling

## Need help

If you need assistance after trying the steps, contact Atlan support: [Submit a request](https://docs.atlan.com/support/submit-request).

---