--- schema_version: "1" id: b806bb8a8f0538df4ee6a68e2698cf4913de5e46888ae16456e44cf180e9ffb1 title: Troubleshoot Prompt Builder collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/prompt_builder_troubleshoot.md canonical_url: https://help.salesforce.com/s/articleView?id=ai.prompt_builder_troubleshoot.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 60ce115be52adaa8ad2479c218ae02f5095dee39f00809582d3b854548ad43af description: Solve common prompt template issues. products: - Agentforce - Cross Cloud release: "264" --- # Troubleshoot Prompt Builder Solve common prompt template issues. ### Required Editions
Available in: Lightning Experience
Available in: Enterprise, Performance, and Unlimited Editions with the Einstein for Platform, or Einstein or Agentforce for Sales or Service add-on, or Agentforce Foundations
## My preview or test fails with an error. If you click **Preview** and an error appears, such as `Internal Server Error`, then check these items before you contact Salesforce Customer Support. - Confirm that Prompt Builder is included with your Salesforce edition and add-ons. Supported editions appear at the top of this page. - Confirm that Einstein is turned on. From Setup, in the Quick Find box, enter Einstein Setup, and then select **Einstein Setup**. [Learn more about enabling Prompt Builder.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_enable.htm&release=264.0.0&type=5 "Enable Einstein in your organization and assign users the appropriate permission set to use Prompt Builder.") - Confirm that you’re assigned the **Prompt Template Manager** or **Prompt Template User** permission set, and that the permission set includes **Execute Prompt Templates**. [Learn more about enabling Prompt Builder.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_enable.htm&release=264.0.0&type=5 "Enable Einstein in your organization and assign users the appropriate permission set to use Prompt Builder.") - If you verified Einstein, licenses, and permissions and the error continues, then wait a few minutes and try again. The issue is often a temporary service interruption. Check [Salesforce Trust](https://status.salesforce.com) before you create a support case. ## My prompt template works in Preview but fails when used in an agent. A prompt template can generate a response in Prompt Builder and still fail when the same template is called from Agentforce Builder or runs in an agent conversation. The agent can pass different input values than the ones you selected in Preview. - If the template uses a retriever, then confirm that the retriever’s data source is active and that the retriever returns results on its own. [Learn more about individual retrievers.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_retriever_individual.htm&release=264.0.0&type=5 "Use individual retrievers in prompt templates to ground your LLM prompts with relevant knowledge. Individual retrievers include retrievers created in AI Models (formerly Einstein Studio) and legacy default retrievers created previously in Data 360.") - If you ground the template with an Agentforce Data Library or unstructured files, then confirm that indexing is complete. [Learn more about Agentforce Data Library troubleshooting.](https://help.salesforce.com/s/articleView?id=ai.data_library_troubleshooting.htm&release=264.0.0&type=5 "Diagnose issues and avoid common pitfalls in your Agentforce Data Library.") - Preview the template again with the same input values that the agent passes at run time. [Learn more about previewing a generated response.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_preview_response.htm&release=264.0.0&type=5 "In the Response section of your workspace, you can review a response that’s grounded with real Salesforce record data.") ## My structured response has missing or blank fields when the Einstein Trust Layer is on. When the Einstein Trust Layer is on and you use Structured Outputs to generate a JSON response, some fields can come back empty or `null`. The Einstein Trust Layer masks personal information, such as names or email addresses, before it sends the prompt to the AI model. If a field isn’t restored after the response returns, then it can appear blank. In the Response section, open Masking Details and note which fields were masked and whether they contain personally identifiable information. Masked personal information is the most common cause. [Learn more about Structured Outputs.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_use_structured_outputs_responses.htm&release=264.0.0&type=5 "Structured Output in Prompt Builder ensures models return responses in a consistent JSON or HTML format, improving reliability for workflows, integrations, and UI rendering.") To review masking settings, see [Einstein Trust Layer Settings](https://help.salesforce.com/s/articleView?id=ai.generative_ai_mask_select.htm&type=5&language=en_US). ## My prompt template doesn’t use the running user’s data access. If a template returns data that a user shouldn’t see, or omits data that they should see, then add an Apex or flow action that filters records before that data is grounded in the prompt template. [Learn more about adding an action.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_add_new_action.htm&release=264.0.0&type=5 "Add a new action such as Flow, Apex, or Retriever to a prompt template.") ## My file is too large to use for grounding. Files used for grounding are limited to 15 MB per request after conversion to the format sent to the AI model. Most AI models support at least one file type for prompt templates. If a file exceeds the limit, then split it into smaller files or summarize the file before you use it as a grounding source. Unsupported files and files that fail conversion are excluded from the request and listed in the Resolution panel. [Learn more about Prompt Builder limits.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_limits.htm&release=264.0.0&type=5 "Learn the numerical limits of prompt templates.") [Learn more about grounding with file inputs.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_ground_file.htm&release=264.0.0&type=5 "Ground generative AI prompt templates with files so the AI model can use documents, spreadsheets, presentations, images, and email text in the resolved prompt.") ## My file was excluded from the prompt template. After you preview or run the prompt template, open the Resolution panel. Info messages confirm PDF conversion or email text extraction. Warning messages list files that were excluded because the file type isn’t supported, conversion failed, conversion timed out, or the file exceeded a size or quantity limit. If the current AI model supports only text inputs, then select a different AI model. For per-type limits, open **Details** on the selected AI model. ## The Object field is missing. Whether you see the **Object** field depends on the prompt template type. - For a Field Generation template, select an **Object** and an **Object Field** when you create the template, before you open the workspace. [Learn more about creating a Field Generation prompt template.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_create_field_gen_prompt_template.htm&release=264.0.0&type=5 "A Field Generation prompt template brings generative AI-assisted workflows to fields within Lightning record pages. Enable your users to populate a field with a summary or description created by an LLM to facilitate more productive conversations with your customers.") - For a Flex template, object resources are optional. Add them later from the **Resources** tab. The **Object** field doesn’t appear on the initial setup screen. [Learn more about creating a Flex prompt template.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_create_flex_prompt_template.htm&release=264.0.0&type=5 "For any use case that isn’t covered by the other template types, a flex prompt template type is your solution. Craft a flex prompt template that uses AI to generate content for your unique business cases.") If you expected to see **Object** immediately and you don’t, then confirm which template type you’re creating. ## I get inconsistent results from the same prompt template. Prompt templates use a large language model (LLM). AI models don’t always return the same response for the same inputs, so results can vary across runs. Templates that use retrievers for classification-style tasks can also fail to parse a response as valid JSON. - Preview the same inputs more than once to see whether the issue is intermittent. [Learn more about previewing a generated response.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_preview_response.htm&release=264.0.0&type=5 "In the Response section of your workspace, you can review a response that’s grounded with real Salesforce record data.") - Make instructions specific, and add explicit handling for empty or unexpected values. [Learn more about refining a prompt template.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_optimize_refine.htm&release=264.0.0&type=5 "Iteratively improve your prompt templates to achieve consistent, high-quality results. Great prompt templates are rarely written perfectly on the first attempt.") - Don’t repeat the same merge field multiple times. Repeated merge fields can lead to inconsistent results. [Learn more about organizing complex prompts.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_organize_complex_prompts.htm&release=264.0.0&type=5 "Structure prompts with multiple data sources and merge fields for clarity and consistency. Well-organized prompts reduce errors, speed up troubleshooting, and produce more reliable AI output.") - If failures are frequent, for example, about one in two runs, then create a support case and include example inputs. ## I get an error while resolving data providers. If you see an error such as `Error occurred while resolving data providers; cannot describe data provider`, then an action in the **Resources** tab is missing, misconfigured, or unavailable. In Prompt Builder, these resources are called actions. They include flow, Apex, and retriever actions. - Open the **Resources** tab and review each action. Confirm that the referenced flow, Apex class, or retriever still exists and that you have access to it. [Learn more about adding an action.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_add_new_action.htm&release=264.0.0&type=5 "Add a new action such as Flow, Apex, or Retriever to a prompt template.") - If you recently renamed, deleted, or deactivated a flow or class, then update or replace the action in the prompt template, and save and preview again. ## I can’t delete an input. You can’t delete an input that’s still referenced by an action. In the **Resources** tab, remove or update the flow, Apex, or retriever action that uses the input. Then delete the input. [Learn more about adding an input.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_add_new_input.htm&release=264.0.0&type=5 "Add a new object, free text input, or data model object to an existing prompt template.") ## My resources or flows are missing after I save and activate. After you save and activate, confirm that you’re viewing the version that contains your resources. Activating a template version makes that version immutable, so it can’t be edited. - Refresh the page, then use the version dropdown at the top of the Prompt Template Workspace to open the version you just activated. [Learn more about using multiple versions.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_use_multiple_versions.htm&release=264.0.0&type=5 "Create and use multiple versions of prompt templates in Prompt Builder to compare prompt constructions and their responses.") - Confirm that the resources were saved on the version that’s now active. If you added a flow or Apex action after activation, then save the work as a new version and activate that version. [Learn more about activating and deactivating prompt templates.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_activate_deactivate_templates.htm&release=264.0.0&type=5 "Use activation and deactivation of prompt templates to finely control which version your users can access.") ## My prompt template fails to save. Save-time validation fails when a merge field, action, or required input isn’t valid. - Check merge field syntax. For example, use `{!$Input:Account.Id}` rather than the Winter ’24 syntax `{!$account.Id}`. - Confirm that every required input has a value and that each action in **Resources** still resolves. [Learn more about adding an input.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_add_new_input.htm&release=264.0.0&type=5 "Add a new object, free text input, or data model object to an existing prompt template.") - If the template uses a flow or Apex class from the Prompt Builder pilot, then recreate those resources for the current syntax. ## My response is masked, flagged for harmful content, or cut off. The Einstein Trust Layer scans prompt template responses for toxic language. When toxic language is detected, the harmful content badge appears in the Response section with a warning count. Revise the prompt template and preview again until the warning count returns to 0. [Learn more about harmful content notifications.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_harmful_content.htm&release=264.0.0&type=5 "Learn how Prompt Builder alerts you to potentially harmful content in a prompt template response.") If the response is cut off, then the resolved prompt can exceed what the AI model accepts. When a prompt is too large, Prompt Builder can generate a summary in the Resolution panel. Use the summarized prompt or shorten the template. [Learn more about working with large prompts.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_large_prompts.htm&release=264.0.0&type=5 "When a prompt is too large for the model to use, a summary is generated automatically in the Resolution panel using OpenAI models . You can decide to use the summarized prompt or create a smaller prompt.") Masked values in the response are expected when the Einstein Trust Layer replaces sensitive data with placeholders and then restores them. Open Masking Details in the Response section to inspect the mapping. [Learn more about data trust and masking.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_get_to_know.htm&release=264.0.0&type=5 "Prompt Builder features a guided, visual layout that takes you through each stage of your prompt’s lifecycle, from creation, to testing, and activation.") ## I need to document and debug my prompt templates. Prompt Builder doesn’t support inline comments in the template body. Use versions to compare changes, and keep a short record of what you changed in each version. - Click **Save As** | **Save as a New Version** before a significant edit so you can compare responses side by side. [Learn more about using multiple versions.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_use_multiple_versions.htm&release=264.0.0&type=5 "Create and use multiple versions of prompt templates in Prompt Builder to compare prompt constructions and their responses.") - Preview with the same test record each time, and note which instruction or resource you changed. - For complex logic, test the instruction text in Preview on its own, then add resources and preview again. [Learn more about organizing complex prompts.](https://help.salesforce.com/s/articleView?id=ai.prompt_builder_organize_complex_prompts.htm&release=264.0.0&type=5 "Structure prompts with multiple data sources and merge fields for clarity and consistency. Well-organized prompts reduce errors, speed up troubleshooting, and produce more reliable AI output.")