# Troubleshooting & FAQ
## Overview
When a component works for you in the builder but fails for end-users on a Lightning Page, the cause almost always falls into one of three categories: the component never renders, the component renders but shows an error, or the component renders empty. This page walks through each scenario, including the checks that actually resolve it, plus a diagnostic checklist for when the symptom doesn't fit a clear category.
Start with the scenario that matches what the user is seeing.
***
## Component Doesn't Appear on the Page
The user opens the record page, and the component slot is missing entirely — no error, no placeholder, just blank space where it should be.
### License and Permission Set Assignment
This is the most common cause when a component works for you (an admin) but is invisible to a standard user.
| Problem | Cause | Fix |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Component is invisible for a specific user | The user doesn't have an Avonni package license assigned | In Setup > Installed Packages, click **Manage Licenses** next to the Avonni package and assign the license to the user |
| Component is invisible for an entire profile | The Avonni permission set is not assigned to that profile or to the users | In Setup > Permission Sets, open the Avonni Dynamic Components permission set and assign it to the affected users |
| Component is invisible after a sandbox refresh | License and permission set assignments don't carry over between environments | Re-assign Avonni licenses and permission sets in the refreshed environment |
| Component is invisible in a different org after deployment | Deploying the page layout doesn't deploy license assignments | Assign Avonni licenses and permission sets in the target org separately from the metadata deployment |
{% hint style="warning" %}
#### Important
Always test as a standard user before assuming a deployment is complete. Admins bypass many permission checks, so a component that renders for an admin can be invisible to everyone else
{% endhint %}
### Visibility Rules Hiding the Component
Avonni components support visibility rules — conditions that show or hide a component based on a custom permission or the running user's context. When the rule evaluates to false, the component renders nothing and gives no visual feedback.
| Problem | Cause | Fix |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| All users see the component, even those who shouldn't | Custom permission check returning `undefined` instead of `false` in earlier package versions | Upgrade to the latest Avonni Dynamic Components package version |
| No users see the component, even those who should | The custom permission referenced in the visibility rule isn't assigned, or the permission set holding it isn't assigned | Confirm the custom permission exists in Setup > Custom Permissions, then verify the permission set containing it is assigned to the right users |
| Component shows for admins but not standard users | System administrators bypass some permission checks; the visibility rule fails silently for standard users | Test the visibility rule with a non-admin user; assign the permission set explicitly to standard user profiles |
| Component visible in builder preview but invisible at runtime | The visibility rule depends on `{!RecordId}` or `{!$User.Id}` which aren't available in preview the same way | Test on the actual Lightning Page, not in builder preview, and confirm the runtime context matches the rule's expectations |
#### Page Assignment and Deployment
| Problem | Cause | Fix |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component appears in the App Builder but not on the live page | The Lightning Page is saved as a draft, or it isn't activated for the right App, Record Type, or Profile | In Lightning App Builder, click **Activation** and confirm the page is assigned to the App, Record Type, or Profile the user is accessing |
| Component disappears after editing the Lightning Page | The page wasn't saved and activated after the edit | Open the page in App Builder, click **Save**, then **Activate** |
| Component is missing only in Experience Cloud | The component is the Dynamic Components version, not the Experience Cloud version | Use the Avonni Experience Cloud Components package for Experience Sites; Dynamic Components only render on internal Lightning Pages and App Pages |
***
## Component Shows an Error Instead of Content
The component renders, but instead of data the user sees an error message or a red banner. This means the component loaded but a query, action, or external call failed.
### Data Source Errors
| Problem | Cause | Fix |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Error references an invalid field | A field referenced in the Data Source query was renamed or deleted in Salesforce | Open the component in the builder, edit the Data Source, and replace the broken field reference with the current API name |
| Error references an unknown object | The object was deleted, or the component was deployed to an org that doesn't have that custom object | Verify the object exists in the target org with the same API name |
| Error mentions "no rows for assignment" or "list has no rows" | The query returned no records but the component expects at least one (often when binding `{!RecordId}` to a non-record page) | Add a filter that handles the empty case, or only display the component on record pages where `{!RecordId}` resolves |
| Error mentions "Insufficient privileges" | The running user lacks Read access to the queried object | Grant Read access to the object via profile or permission set, or restrict the component to user groups that have access |
| Error mentions "MALFORMED\_QUERY" or "unexpected token" | The filter syntax doesn't match SOQL rules — usually a missing quote around a string value or an invalid operator | Open the filter in the builder, confirm string values are surrounded by quotes, and that the operator matches the field type |
### Field-Level Security Errors
When a user has access to the object but not to a specific field referenced by the component, the result depends on the **Strip Inaccessible Fields** setting on the Data Source.
| Problem | Cause | Fix |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component errors out for some users with "field not accessible" | A field referenced in the query is hidden by field-level security for that profile, and Strip Inaccessible Fields is off | Enable **Strip Inaccessible Fields** on the Data Source, grant FLS on the field via permission set, or remove the field from the query |
| Component loads for the admin but errors for standard users | FLS differs between profiles — admins see all fields by default | Test as a standard user; enable Strip Inaccessible Fields as a safety net, or audit FLS on all fields used in the component |
| Strip Inaccessible Fields is on but the component still errors | The user lacks access to the **object** itself, or to a related object in a lookup chain (e.g., `Contact.Account.Name` when Account access is denied) | Strip Inaccessible Fields only removes inaccessible fields from results — it cannot recover from object-level access failures. Grant Read access to the related object |
### External Resource and Apex Errors
| Problem | Cause | Fix |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Component shows a broken image or fails to load an external URL | The URL host isn't allowed by your org's Content Security Policy (CSP) | In Setup > CSP Trusted Sites, add the external domain. Salesforce blocks external resources from untrusted domains by default |
| Component calls Apex and errors on load | The user lacks access to the Apex class | Grant access to the Apex class via permission set: Setup > Permission Sets > \[the set] > Apex Class Access |
| Apex call returns an error string instead of data | The Apex method throws an uncaught exception | Open the Apex class in the Developer Console, run the method with sample inputs, and add a try/catch that returns a meaningful error |
| Embedded URL or iframe shows "refused to connect" | The target site sets `X-Frame-Options: DENY` or `frame-ancestors` to block embedding | The site cannot be embedded — use a regular link instead of an iframe, or contact the site owner |
***
## Component Loads but Shows No Data
The component renders, no error is displayed, but the result area is empty — no records, no rows, no chart bars.
| Problem | Cause | Fix |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The query returns no records for the running user | Sharing rules restrict the user's access to records, even though they have object and field access | Log in as an admin and load the same page. If the admin sees records but the user doesn't, the issue is sharing — review Sharing Settings, Sharing Rules, and Role Hierarchy for the affected object |
| The filter is too restrictive | A hardcoded filter value doesn't match any records, or `{!RecordId}` resolves to an empty value on a page that isn't a record page | Open the Data Source and simplify the filter until records appear, then add back filters one by one to find the breaker |
| Variables in the filter aren't resolving | `{!RecordId}` is used on a Home page or App page, where there's no record context | Use the component only on record pages, or replace `{!RecordId}` with a different variable like `{!$User.Id}` |
| Component is empty only for certain users | Field-level security with Strip Inaccessible Fields enabled is silently removing all visible fields | Audit FLS — if every queried field is blocked, the component can't render anything. Grant access to at least the display fields |
| Data appears in builder preview but not at runtime | The Preview Context in the Debug Panel uses a record that the running user can't access | Switch the Preview Context to a record visible to the target user, or test directly on the Lightning Page |
***
## Common Error Messages
A quick reference for error strings that users may report.
| Error Message | What It Means | Where to Look |
| ---------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
| **Insufficient privileges** | The user lacks Read access to the object | Profile or permission set object permissions |
| **Field is not accessible** | Field-level security blocks a queried field | Permission set FLS or enable Strip Inaccessible Fields |
| **No access to entity: \[Object]** | Object access denied at the API level | Object permissions on the running user's profile |
| **Invalid field reference** | A queried field was renamed or deleted | Open the component's Data Source and update the field |
| **MALFORMED\_QUERY** | The SOQL filter has a syntax error | Filter values, quotes, and operators in the Data Source |
| **Apex CPU time limit exceeded** | An Apex call exceeded Salesforce's 10-second limit | Apex method performance — paginate or filter further upstream |
| **You don't have access to this record** | Sharing rules block the specific record | Sharing settings, role hierarchy, or manual sharing |
| **Unable to load component** | The component definition couldn't be retrieved | Avonni license assignment and permission set |
***
## Diagnostic Checklist
When the symptom doesn't fit a clear category, work through these steps in order. Each one rules out one cause.
{% stepper %}
{% step %}
#### Reproduce the problem as the affected user
* Use the **Login As** feature in Setup > Users > \[user] > Login to confirm the symptom firsthand
* *Why: Many issues only appear under a specific profile, permission set, or sharing context. Reproducing as the user is faster than guessing*
{% endstep %}
{% step %}
#### Check the browser console
* Open the browser developer tools (F12 on most browsers) and reload the page
* Look for red error messages in the **Console** tab
* *Why: Salesforce often logs the real error to the console even when the UI shows a generic message.*
{% endstep %}
{% step %}
#### Verify license and permission set
* Confirm the user has an Avonni package license in Setup > Installed Packages > Manage Licenses
* Confirm the user is assigned to the Avonni permission set
* *Why: Missing licenses are the single most common cause of "component is invisible" reports*
{% endstep %}
{% step %}
#### Compare with an admin
* Load the same page as a System Administrator
* If the admin sees the component working, the issue is almost always permissions, FLS, or sharing
* If even the admin sees the error, the issue is in the component configuration itself
{% endstep %}
{% step %}
#### Test the Data Source query in isolation
* Copy the SOQL filter from the Data Source
* Run it in the Developer Console > Query Editor as the affected user
* *Why: If the query fails in the Query Editor, it will fail in the component. This separates query problems from component problems*
{% endstep %}
{% step %}
#### Check the page activation
* Open the Lightning Page in App Builder and click **Activation**
* Confirm the page is activated for the App, Record Type, and Profile the user is using
{% endstep %}
{% endstepper %}
***
### Still Need Help
If nothing on this page resolves the issue, reach the Avonni team.
* Email Support: [**support@avonni.app**](mailto:support@avonni.app)
* **Report a Bug** — See the [Bug Reporting Guide](/dynamic-components/resources/report-bugs.md)
* [**Community Forum**](https://trailhead.salesforce.com/trailblazer-community/groups/0F9KX000000iFxO0AU?tab=discussion\&sort=LAST_MODIFIED_DATE_DESC) — share experiences with other Dynamic Components users
Before contacting support, gather the following so the team can resolve faster:
1. Exact error message (copied from the screen or browser console)
2. Steps to reproduce, in order
3. Screenshots of the component configuration and the error
4. Avonni package version (Setup > Installed Packages)
5. Expected behavior vs. actual behavior
6. Whether the issue is reproducible in multiple browsers
7. Whether the issue is reproducible across different user permissions or only for specific users
***
## FAQs
Can I copy components between orgs?
Yes. Dynamic Components are stored as Custom Metadata records, making them portable with standard Salesforce deployment tools (change sets, SFDX, packaging). Each component is a single metadata record containing its full definition — layout, data sources, styling, interactions, and logic.
How many components can I create?
There's no hard limit. Create as many as you need — but consider the maintenance overhead and how you'll organize them.
Do Dynamic Components work offline?
No. Like all Lightning components, Dynamic Components require a server connection.
How do I migrate components from sandbox to production?
Use standard Salesforce deployment tools — change sets, SFDX, or unmanaged packages — since components are stored as Custom Metadata records. See the [**Deploying Dynamic Components Guide**](/dynamic-components/resources/deployment-process.md) for the full process.
Can I white-label Dynamic Components?
Yes. Full styling control lets you match any branding — colors, typography, spacing, custom CSS.
WhWhat's the performance impact of Dynamic vs. App Builder components?
On **warm loads** (after the org's first visit), a well-built Dynamic Component performs on par with a native Lightning component.
On **cold loads** (the very first visit or after the 48-hour Salesforce cache expires), Dynamic Components incur a higher compilation cost because Salesforce can't bundle them in advance — each is fetched and compiled individually at runtime. This affects every page that uses dynamically loaded Lightning components, not just Avonni. The trade-off buys you the no-code builder and runtime flexibility.
See the [**Performance Guide**](/dynamic-components/resources/performance-guide.md) for ways to reduce cold-load time.
Can I use Dynamic Components on mobile?
Yes. Components work in the Salesforce mobile app. Test thoroughly — some interactions and layouts behave differently on small screens.
How do I debug component logic?
Use the browser developer console (F12), Lightning Debug Mode, the Avonni Debug Panel, and Salesforce debug logs for server-side operations.
Why is the first load so slow? Is something wrong?
No — that's expected Salesforce platform behavior. When a Lightning Page is opened for the first time, Salesforce compiles every component server-side before delivering the page. The result is cached at the org level for 48 hours and shared across all users, so subsequent loads are much faster.
Pages with many components, or with heavy components like Data Tables and Repeaters, will feel slower on cold load because there's more for Salesforce to compile. This applies to every dynamically-loaded Lightning component, not just Avonni.
See [Understanding First-Load Performance](/dynamic-components/resources/performance-guide.md#understanding-first-load-performance) for the full explanation and what we're doing about it.
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.avonnicomponents.com/dynamic-components/resources/troubleshooting-and-faq.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.