Troubleshooting

Enable Cloud Logging for your agent

Activate Cloud Logging for your agent. This is essential for capturing data and diagnosing problems in real conversations.

Collect conversation IDs

When unexpected behavior occurs, collect the Dialogflow conversation IDs. These IDs, found in the Conversation History, provide a way to trace the execution path of a conversation and examine specific interactions.

API call gets permission denied

Issue

Received PERMISSION_DENIED response for API call.

Solution

Ensure you have set up (Dialogflow CX, Dialogflow ES) authentication and roles correctly. In particular, ensure you have done the following:

  • Created a service account and did not accidentally delete it.
  • Provided the service account with a role that grants permission to call the chosen method.
  • Downloaded the service account private key file.
  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the private key file.

API call mentions unknown project

Issue

Received Dialogflow API has not been used in project 32555940559 error for API call.

Solution

Ensure you have done the following:

  • Set the GOOGLE_APPLICATION_CREDENTIALS environment variable (see PERMISSION_DENIED).
  • Provided the correct project ID to the API call.

API call gets invalid authentication credentials error

Issue

Received Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. response for API call.

Solution

This may be due to manually creating credentials with your client library while specifying a non-default region. See one of the following for guidance:

API call response requests a switch to a different host

Issue

Received Please switch to 'REGION-dialogflow.googleapis.com' to access resources located in 'REGION' response for API call, where REGION is a specific region ID.

Solution

This happens when you specify the region in the request, but not the endpoint. See one of the following for guidance:

Missing fields in the API call response

Issue

Some fields are missing in the API response.

Solution

If you expect a numeric value for a specific field in the API response, the field may be absent from the response if the returned value is 0.

For more information on the default value behavior (including non-numeric values), see:

Unable to delete project because of lien

Issue

When trying to delete a Google Cloud project, you get a notification that the project cannot be deleted because it has liens, and one of the liens is related to Dialogflow ES.

Solution

  1. Make sure that you no longer need the Dialogflow ES agent associated with the project. If you get a notification that the agent doesn't exist, this means that it has already been deleted.

    Dialogflow ES Console

    Open https://dialogflow.cloud.google.com/#/agent/project-id/intents.

    Note that this link differs from the link in the Google Cloud project deletion dialog.

    Dialogflow API

    Use the search method of the agent type.

  2. Get the lien name.

    gcloud

    Use the gcloud alpha resource-manager liens list command, as described in the Listing liens on a project documentation.

    API Explorer

    Use the Try this API panel on the Method: liens.list page:

    • Fill out the parent field, as suggested in the parameter description.
    • Click Execute.
  3. Delete the lien.

    gcloud

    Use the gcloud alpha resource-manager liens delete LIEN_NAME command, as described in the Removing liens from a project documentation.

    API Explorer

    Use the Try this API panel on the Method: liens.delete page:

    • Fill out the name field with the lien name that you got in step 2.
    • Click Execute.
  4. Shut down the project.

Dialogflow CX webhook fails with deadline exceeded error

Issue

A webhook that was called from Dialogflow CX may fail with this error message:

Webhook call failed. Error: DEADLINE_EXCEEDED

This may happen because the webhook call exceeds the webhook timeout limit. These are possible reasons for the webhook call to exceed the timeout limit:

  • Trying to trigger an inexistent intent.
  • A cold start issue with the webhook backend (for example, Cloud Functions).
  • The webhook calls other services, increasing the response time.
  • No connection between agent and webhook backend (for example, misconfigured Load Balancer).
  • Organization policy preventing ingress traffic or Dialogflow methods from being run.

Workaround

A webhook has a 5-second timeout limit by default. You can increase the webhook timeout limit when you create or edit the webhook resource, which would provide more time for the webhook to respond.

Console fails to set up project

Issue

Received Failed to set up GCP project error when creating an agent with the console.

Solution

You may not have permission to create Google Cloud projects. Check if you can create a Google Cloud project directly from the console. If you cannot create a project, follow the recommendations provided in the error message.

Session parameter reference shown in the response

Issue

Responses returned from Dialogflow include the parameter references instead of the values of the parameters. For example:
Hello, $session.params.customer_name

The parameters won't be resolved, and the parameter reference will be shown if the parameter is not found in the current session or if the parameter is not being used according to its type.

Solution

This issue may appear due to the parameter used not being included in the conversation, having a typo, or having a different type than the used type.

Console fails agent creation when API has not been enabled

Issue

Received Dialogflow API has not been enabled for the project. Code: FAILED_PRECONDITION error when creating an agent with the console.

Solution

Follow the setup steps to enable the Dialogflow API.

When attempting to access console from organization account, received service error

Issue

Received You don't have access to this service error when attempting to access the console from your organization account.

Solution

Contact your organization's system administrator and verify that your organization's settings provide access to the console. Otherwise, check if your migrated account from a different organization has been flagged as restricted by Google — this is likely the problem if other users in your organization can access the console, but you can't.

Alternatively, contact support to get assistance.

Cannot export agent in JSON format due to missing flow

Issue

Agent export as raw bytes completes successfully, but exporting the agent in JSON format fails with an error message similar to this:

Flow 'projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/flows/FLOW_ID' does not exist
in the agent

This issue can be caused by a test case referencing a flow that has been deleted.

Solution

To solve this issue, explore unused test cases to confirm if the flow referenced in the error message is being used in any test cases, then delete the confirmed test cases.

Phone gateway connectivity

Issue

When using a Phone Gateway, you get a busy signal or the call drops.

Solution

There are quotas and limits for this feature. If you receive a busy signal or the call drops, you may have exceeded your quota.

RESOURCE_EXHAUSTED error when trying to create a new phone number

Issue

When trying to create a new phone number in Dialogflow CX, Dialogflow ES, or Agent Assist, a RESOURCE_EXHAUSTED error is returned.

Solution

This error means that you exceeded the limit of phone numbers per project. To create a new phone number, delete unused phone numbers associated with your project until you are below the limit.

If you created phone numbers in the Dialogflow CX Phone Gateway or Dialogflow ES Phone Gateway, you can delete them in the console. Note that deleting the agent without deleting the phone number doesn't delete the phone number associated with it.

Alternatively, you can use the API by performing the following steps.

Step 1. Identify all phone numbers associated with your project

To identify the phone numbers associated with your project, use the projects.phoneNumbers/list or projects.locations.phoneNumbers.list API method for all regions in which you may have created phone numbers.

  • For the global region, use the following command:

    curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/phoneNumbers
    
  • For other regions, you need to specify the region in two places:

    curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/phoneNumbers
    

Step 2. (Optional) Identify agents associated with the conversation profiles

Getting the Dialogflow CX agent ID associated with the phone number through the conversation profile could help you identify if the agent is still in use and if the phone number is still needed. You can do this by using the projects.conversationProfiles/get API method. You can find conversation profile IDs in the responses to the commands you ran in step 1.

  • For the global region, use the following command:

    curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/global/conversationProfiles/CONVERSATION_PROFILE_ID
    
  • For other regions, specify the region in two places:

    curl -X GET \
    -H "Authorization: Bearer "$(gcloud auth print-access-token) \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    https://REGION_ID-dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/locations/REGION_ID/conversationProfiles/CONVERSATION_PROFILE_ID
    

You can find the agent by its ID in the Dialogflow CX console by using the Search option on the View all agents page.

For Dialogflow ES, one project can be associated only with five agents maximum, and one Dialogflow ES agent can be associated with one phone number. So you can open the agent in the Dialogflow ES console through https://dialogflow.cloud.google.com/#/editAgent/PROJECT_ID/intents.

If no agent is found, you can still delete the phone number if you are sure it's no longer needed.

Step 3. Delete unused phone numbers

To delete phone numbers that are no longer needed, use the projects.phoneNumbers/delete or projects.locations.phoneNumbers.delete API method. You can find phone number IDs in the response to the commands you ran in step 1.

  • For the global region, use the following command:

    curl -X DELETE \
        -H "Authorization: Bearer "$(gcloud auth print-access-token) \
        -H "X-Goog-User-Project: PROJECT_ID" \
        -H "Content-Type: application/json; charset=utf-8" \
        https://dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
    
  • For other regions, specify the region:

    curl -X DELETE \
        -H "Authorization: Bearer "$(gcloud auth print-access-token) \
        -H "X-Goog-User-Project: PROJECT_ID" \
        -H "Content-Type: application/json; charset=utf-8" \
        https://REGION_ID-dialogflow.googleapis.com/v2beta1/PHONE_NUMBER_ID
    

Dialogflow CX Messenger no response

Issue

No agent response for Dialogflow CX Messenger interactions.

Solution

If you are not seeing any responses from Dialogflow CX Messenger, make sure that billing is enabled on the project and the Dialogflow API is enabled on the project. See the setup instructions.

Parameter value matched while not being an entity synonym

Issue

  • General case: A parameter value is extracted at runtime, even though the entity corresponding to the parameter doesn't contain the matched value as a synonym.
  • A more specific case: After a synonym has been deleted from an entity and the agent has been retrained, this synonym is still extracted as a parameter value for this entity.

Solution

  1. Use the search option to check if the matched value may be present in the agent as an implicit entity (Dialogflow CX, Dialogflow ES). Find all the intents that have annotations with this parameter and entity.
  2. Fix the annotations by making sure that none of these annotations are applied to the text representing the undesired matched value.
  3. Test the agent at runtime to verify if the issue is resolved.
  4. If the issue persists, make sure that Automatic expansion and Fuzzy matching options are unchecked in the advanced entity settings, and test the agent again.

Voice bot skips some responses

Issue

For an agent designed for both text and voice, the voice bot does not read some responses.

Solution

If at least one output audio text response is defined for a particular conversation turn, make sure that the output audio text option is consistently present throughout the agent's fulfillment and webhook responses at all steps for this conversation turn.

SSML tags don't take effect

Issue

SSML tags are defined in the agent fulfillment, but the voice bot reads the synthesized text without SSML effects.

Solution

Make sure that only one <speak></speak> pair is present per one response card in the Dialogflow console, or per one response message object if responses are supplied by the API or webhook.

Voice agent pronounces zero as letter O

Issue

For an agent designed for voice, the voice agent reads zeroes as letter O instead of zero.

Solution

  1. Change Agent says to use Output audio text dialogue option.
  2. Check SSML checkbox.
  3. Surround your text with an SSML tag:
      <speak>
        <say-as interpret-as='verbatim'>YOUR_TEXT</say-as>
      </speak>
  4. Save.

For example, credit card numbers zeroes will be spelled as zeroes:

   <speak>
      <say-as interpret-as='verbatim'>5177 7702 8500 4578</say-as>
   </speak>

Unexpected synthesized pronunciation

Issue

Synthesized pronunciation of agent responses (e.g., proper names, acronyms) is not as expected.

Solution

To guarantee particular pronunciations for not commonly known words, use the SSML say-as or phoneme tag in agent responses.

Reached the maximum allowed state machine execution steps

Issue

Received the following error message in the Dialogflow CX console or in the logs when sending runtime requests to the agent:

You have reached the maximum allowed state machine execution steps. You may consider simplifying your agent/flow design. Current execution steps are: [<array_of_objects>]

The array in the error message contains a list of execution steps for the request. The list may be incomplete if the number of steps is too large.

Solution

This error message usually indicates that the number of transitions for a single conversation turn is too large. A common example is transitioning to the same page, which creates an infinite loop.

To solve the issue:

  1. Copy the JSON array from the error message.
  2. (Optional) Format the copied array as pretty JSON for better readability. If the error message is truncated, search for the last "Step" object, delete the incomplete step object and the preceding comma, and add a closing array bracket before validating and prettifying the JSON.
  3. Look at the "TriggeredTransitionRouteId" and "TargetPage" values for each step. In the case of infinite loop, the "TriggeredTransitionRouteId" and "TargetPage" fields have repeating values for most of the steps.
  4. Modify your agent design to remove the infinite loop transitions or to reduce the number of transitions for a single conversation turn.

Regular expression match is too broad

Issue

Received an error Regular expression match is too broad when creating a regexp entity (Dialogflow CX, Dialogflow ES).

Solution

Consider the following approach:

  • Use ^ and $ in the regular expression to indicate the beginning and the end of text, respectively.
  • Use the regexp entity with a required parameter (Dialogflow CX, Dialogflow ES).
  • Define the required parameter prompts to ask the end-user to provide only th entity value without any surrounding words.

Undesired non-alphanumerics inserted by speech recognition

Issue

When trying to match alphanumerics, undesired non-alphanumerics characters (spaces, dashes, etc.) are inserted by the speech recognizer, which results in the entity not being matched.

Solution

  1. If you use system entities for matching numbers, consider using regexp entities (Dialogflow CX, Dialogflow ES) instead.
  2. Follow all the recommendations from the section Inaccurate alphanumerics speech recognition by regexp entities.
  3. For matching numbers using telephony integrations, consider a DTMF option, in addition to voice recognition.

Empty transcripts for voice inputs

Issue

Dialogflow responses for voice inputs return empty transcripts. The requests are handled as no input or no match.

Solution

Listen to the audio recording to confirm that it contains speech.

Make sure that speech adaptation is enabled in the agent settings (Dialogflow CX, Dialogflow ES).

If enabling speech adaptation doesn't help, experiment with the following speech models in a non-production setup and use the one that renders the best results:

  • latest_short
  • phone_call
  • command_and_search

For languages other than English, find the supported speech models in the Speech-to-Text supported languages documentation.

The way to specify a speech model depends on how you set up interactions with Dialogflow.

  • For API requests, provide the model name in the model field in InputAudioConfig (Dialogflow CX, Dialogflow ES).

  • If you use Phone Gateway (Dialogflow CX, Dialogflow ES), you can update the speech model in the conversation profile that was created by Dialogflow when you enabled the integration:

    1. Retrieve the conversation profile ID:

      • Use the conversationProfiles.list method to retrieve all conversation profiles linked to your project.
      • Find the conversation profile you'd like to update and copy the name field value.

      For Dialogflow CX Phone Gateway, the conversation profile display name can be found in the integration settings. For Dialogflow ES Phone Gateway, the conversation profile display name corresponds to the agent name in which integration was enabled.

      If you have multiple conversation profiles with the same display name, verify the agent ID in the automatedAgentConfig field from the conversationProfiles.list method response.

    2. Use the conversationProfiles.patch API method to update the model field in SpeechToTextConfig.

  • For Contact Center AI integrations, check with your telephony integrator on how to update the speech model for the integration or for individual requests.

Understanding playbook loop errors

Issue

When linking playbooks, you are encountering error Playbook <playbookID> caused loop in playbook routes.

Solution

A loop can occur if you attempt to route to an "ancestor" playbook—one that directly or indirectly called the current one. To fix this, verify that your playbook routing is unidirectional and doesn't circle back to a parent playbook in the same conversational path.

Blank screen error 'File size exceeds 2MB' when comparing agent versions

Issue

When trying to compare two different agent versions, the screen turns blank with the error message:

File size exceeds 2MB

This issue is due to one of the files exceeding 2MB in size.

Solution

To compare agent versions where one of the files exceeds 2MB in size, it's recommended to use the API method compareVersion.

Inaccurate alphanumerics speech recognition by regexp entities

Issue

Received inaccurate transcripts for voice inputs of alphanumerics designed to be matched to a regexp entity (Dialogflow CX, Dialogflow ES).

Solution

  1. Make sure that speech adaptation is enabled in the agent settings (Dialogflow CX, Dialogflow ES).
  2. Make sure that at least one entity entry follows all the regex entry requirements (Dialogflow CX, Dialogflow ES).
  3. For specific patterns, use the most specific regular expressions. For example, for an alphanumeric that starts with two letters followed by five digits, use [a-zA-Z]{2}\d{5} instead of [a-zA-Z0-9]{7}.
  4. Make sure that your regexp entity allows for matching non-alphanumerics (spaces, dashes, etc.) that may be inserted by the speech recognizer. To meet the requirement 2 from this list, create multiple entity entries: one entry to satisfy the requirements 2 of this list and another to account for non-alphanumeric. For example, to match five digits and allow for non-alphanumerics:
     \d{5}
     (\d[^a-zA-Z0-9]*){5}
    
  5. Make sure that your agent follows the parameter definition requirement (Dialogflow CX, Dialogflow ES).

    Example for Dialogflow CX

    Required parameter in Dialogflow CX

    Example for Dialogflow ES

    Required parameter in Dialogflow ES
  6. Make sure that your agent follows the training phrases annotation requirement (Dialogflow CX, Dialogflow ES).

    Example for Dialogflow ES

    No annotations in training phrases in Dialogflow ES
  7. Make sure that your tests follow the testing guidelines (Dialogflow CX, Dialogflow ES).
  8. To remove non-alphanumeric characters that may have been inserted by the speech recognizer, use the following:
  9. Check speech adaptation limitations (Dialogflow CX, Dialogflow ES).

Webhook fails with 403 Forbidden error for Cloud Run functions (2nd gen)

Issue

When calling a webhook hosted on Cloud Run functions (2nd gen) from Dialogflow CX, the webhook fails with an HTTP 403 Forbidden error or the following message in the function logs:

The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.

Cause

Unlike Cloud Run functions (1st gen) which feature built-in authentication for Dialogflow CX webhooks, Cloud Run functions (2nd gen) run on Cloud Run and require IAM invoker permissions. If the Dialogflow CX service agent account does not have permission to invoke the Cloud Run service, calls are rejected with an HTTP 403 error. For details on the differences between versions, see the Cloud Run functions version comparison.

Resolution

Grant the Cloud Run Invoker role to the Dialogflow CX service agent:

  1. Identify your PROJECT_ID project number.
  2. In the Google Cloud console, go to the IAM page.
  3. Select the Include Google-provided role grants checkbox.
  4. Locate the Dialogflow CX service agent account: service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com (replace PROJECT_NUMBER with your project number).
  5. Assign the Cloud Run Invoker (roles/run.invoker) role to the service agent account.
  6. Alternatively, configure the Cloud Run function to allow unauthenticated invocations if permitted by your organization policies.

GitHub integration error: Resource not accessible by personal access token

Issue

When attempting to push agent changes to or restore from GitHub in the Dialogflow CX console, the operation fails with the following error:

Received an error from GitHub: Resource not accessible by personal access token

Cause

The personal access token configured for the GitHub connection does not have the required repository permissions to push or restore agent files.

Resolution

Update the permissions for the GitHub personal access token:

  • Fine-grained personal access tokens:
    1. In GitHub, go to your personal access token settings.
    2. Under Repository permissions, set Contents to Read and write.
    3. Verify that Metadata is set to Read-only (automatically selected when Contents permission is granted).
  • Classic personal access tokens:
    1. Ensure the token has the repo scope selected.

Additionally, verify that the specified repository and branch exist and that the account associated with the token has write access to the repository.

Webhook fails with Service Directory resolution or timeout error

Issue

When calling a private webhook using Service Directory from Dialogflow CX, the webhook fails with an error message similar to one of the following:

  • Failed to resolve Service Directory: [projects/PROJECT_ID/locations/LOCATION_ID/namespaces/NAMESPACE_ID/services/SERVICE_ID]
  • DEADLINE_EXCEEDED ... URL_TIMEOUT ... Reason: TIMEOUT_WEB

Cause

  • Missing permissions: The Dialogflow CX service agent account does not have the required IAM roles to access the Service Directory service or Private Service Connect.
  • Disabled global access: For internal Application Load Balancers, global access is disabled, preventing Dialogflow CX from reaching the backend from regions outside the load balancer's region.

Resolution

  1. Identify your PROJECT_ID project number.
  2. In the Google Cloud console, go to the IAM page for the project that hosts your Service Directory service.
  3. Select the Include Google-provided role grants checkbox.
  4. Locate the Dialogflow CX service agent account: service-PROJECT_NUMBER@gcp-sa-dialogflow.iam.gserviceaccount.com (replace PROJECT_NUMBER with the project number of your Dialogflow CX agent project).
  5. Assign the following roles to the service agent account:
    • Service Directory Viewer (roles/servicedirectory.viewer)
    • Service Directory PSC Authorized Service (roles/servicedirectory.pscAuthorizedService)
  6. If the Service Directory service resides in a different project than your Dialogflow CX agent, also ensure the service agent account has the Service Directory Viewer (roles/servicedirectory.viewer) role in the agent's host project.
  7. If using an internal Application Load Balancer and encountering timeout errors (TIMEOUT_WEB), ensure that Global access is enabled on the load balancer frontend.

Text-to-Speech fails with invalid SSML error for Neural2 voices

Issue

When using Neural2 voices for Text-to-Speech in Dialogflow CX, agent responses fail to synthesize audio and the following error occurs:

While calling Cloud Text-to-Speech API: Invalid SSML. Newer voices like Neural2 require valid SSML.

Cause

Neural2 voices strictly enforce XML and SSML compliance. Unlike older voice tiers that tolerate unescaped characters or unquoted attributes, Neural2 rejects malformed SSML, such as missing quotes around attribute values (for example, <prosody rate=100%> instead of <prosody rate="100%">), unclosed tags (for example, missing <break /> or </prosody>), or unescaped XML special characters (&, <, >).

Resolution

  1. Ensure all SSML attribute values are enclosed in quotation marks. For example: xml <speak> <break time="2s" /> <prosody rate="100%" pitch="-0.5st">Hello, how can I help you today?</prosody> </speak>
  2. Verify that all elements are properly nested within the root <speak>...</speak> element and have matching closing tags.
  3. Escape XML special characters in dynamic parameter values and text prompts:
    • Replace & with &amp;
    • Replace < with &lt;
    • Replace > with &gt;
  4. Review the SSML reference for syntax requirements and supported tags.

GitHub integration error: Agent export or push fails due to 500-file limit

Issue

When attempting to export or push a Dialogflow CX agent to a GitHub repository, GitHub returns a server error.

Cause

The agent is too large to be exported directly to GitHub. GitHub restricts updates that contain more than 500 files in a single push. This scenario is most common when attempting to push an agent for the first time to an empty repository, as it generates and pushes the entire file set at once.

Resolution

  1. In the Dialogflow CX console, export the agent as a .zip file.
  2. Upload the unzipped files to GitHub using the GitHub web interface or the Git CLI.
  3. Push subsequent changes directly from Dialogflow CX, assuming each future update modifies fewer than 500 files.

Generative agent fails with sys.agent-banned-phrase error

Issue

A generative agent or playbook repeatedly fails, triggering fallback routes or returning sys.agent-banned-phrase even when user inputs are benign:

Sorry, something went wrong.

Cause

A term configured in the agent's Banned phrases list is present in the agent's internal prompt configuration (such as playbook instructions, goals, examples, or data store tool prompts). Because the banned phrases guardrail evaluates the entire internal LLM prompt (including instructions, conversation history, and user input), any banned phrase present in the instructions triggers the safety filter automatically.

Resolution

  1. In the Dialogflow CX console, go to Agent settings > Banned phrases.
  2. Review the list of configured banned phrases.
  3. Check your playbook instructions, goals, examples, and data store prompt templates for any occurrences of those banned phrases.
  4. Remove or rephrase the matching terms in your internal instructions so they do not overlap with the banned phrases list.

Speech recognition fails with Phrases cannot be empty error

Issue

Voice interactions fail or calls drop unexpectedly with an INVALID_ARGUMENT error:

While calling Cloud Speech API: Phrases cannot be empty

This error can occur even when speech adaptation appears disabled in the Dialogflow CX console.

Cause

Residual speech adaptation settings remain in the page's underlying configuration. If manual speech adaptation was previously enabled, populated with biasing phrases, and subsequently disabled, empty phrase set blocks can persist in the page configuration and cause validation errors in Cloud Speech-to-Text models.

Resolution

Clear the residual speech adaptation settings in the Dialogflow CX console:

  1. Open the flow and navigate to the page where the error occurs.
  2. Temporarily enable Manual speech adaptation in the page settings.
  3. Delete any existing phrase sets and empty phrase entries.
  4. Click Save.
  5. Disable Manual speech adaptation.
  6. Click Save and test the agent.

diagnosticInfo missing from DetectIntentResponse in Cloud Logging

Issue

When inspecting DetectIntentResponse or QueryResult log entries in Cloud Logging, the diagnosticInfo field is missing from the logged response.

Cause

Cloud Logging has a log entry size limit of 256 KB. If the total response payload is large (for example, containing extensive session parameters, large webhook payloads, or detailed query results), Dialogflow CX truncates the diagnosticInfo field so the log entry does not exceed the 256 KB limit.

Resolution

To access diagnostic information or reduce log entry sizes:

  1. Capture diagnosticInfo directly from client-side API responses rather than relying solely on Cloud Logging.
  2. In the Dialogflow CX console simulator, view the full un-truncated payload in the Original response tab.
  3. Reduce the size of webhook responses by returning only necessary parameters and fields in WebhookResponse.

Permission denied error when connecting Avaya telephony integration

Issue

When attempting to connect the Avaya one-click telephony integration in the Dialogflow CX console (Integrations > One-click Telephony > Avaya > Connect), the request fails with the following error:

PERMISSION_DENIED: Policy update access denied

Cause

The user account attempting to enable the Avaya integration lacks permission to update IAM policies on the Google Cloud project. Connecting the Avaya integration requires granting permissions to the Avaya service account on the project.

Resolution

Grant the required IAM role to the user account configuring the integration:

  1. In the Google Cloud console, go to the IAM page.
  2. Ensure the user account has the Project IAM Admin (roles/resourcemanager.projectIamAdmin) role or a custom role containing the resourcemanager.projects.setIamPolicy permission.
  3. Once granted, reconnect the Avaya telephony integration in the Dialogflow CX console.

Webhook fails with target page does not exist error

Issue

When a webhook returns a transition response in Dialogflow CX, the runtime execution fails with the following error:

Page '<PageId>' does not exist in the agent.

This may also appear in Cloud Logging as:

BadRequestException: Page '<PageId>' does not exist in the agent.

Cause

The webhook returned a targetPage transition to a page that isn't in scope. In Dialogflow CX, page transitions are scoped to the current active flow. If targetPage specifies an invalid page ID, an unqualified page identifier, or a page that resides in a different flow, Dialogflow CX can't resolve the transition at runtime.

Resolution

  1. Verify that the target page exists within the same flow where the webhook is invoked.
  2. When constructing the WebhookResponse, ensure targetPage specifies the full canonical resource name: projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/flows/FLOW_ID/pages/PAGE_ID
  3. If you need to transition to a page in a different flow, use the targetFlow field instead to transition to the target flow.

Webhook URL or configuration changes missing from Audit Logs

Issue

A webhook URL or configuration was modified in Dialogflow CX, but there is no record of the change in the console Change History or Cloud Audit Logs.

Cause

By default, only Admin Activity audit logs are enabled in Google Cloud. Modifying webhook configurations or updating agent resource settings requires Data Access audit logs (specifically Data Write logs) to be captured in Cloud Logging.

Resolution

To ensure all future webhook modifications and configuration updates are recorded:

  1. In the Google Cloud console, go to the IAM & Admin > Audit Logs page.
  2. In the list of services, select Dialogflow API.
  3. In the configuration panel on the right, select the Data Write (and optionally Data Read) checkbox under Log Type.
  4. Click Save.

Incomplete audio playback on telephony integrations

Issue

During a phone call with a virtual agent on a third-party telephony platform (such as Genesys), the agent stops speaking before completing the message. The conversation transcript in the console displays the full text, but the caller only hears the first sentence or chunk.

Cause

Dialogflow CX returns fulfillment responses as an array of message objects in the responseMessages payload to support sequential speech, prompts, and barge-in. Some telephony integrations and AudioHook adapters only play the first message object in the array by default unless configured to iterate through the entire message array.

Resolution

  1. In your telephony integration or connector settings, ensure the integration is configured to process and play all message objects returned in the responseMessages array.
  2. Alternatively, in the Dialogflow CX console, consolidate multi-part responses into a single text or audio response card within the page fulfillment rather than splitting text across multiple response cards.

sys.no-input event handler doesn't trigger for text-based agents

Issue

A text-based chat agent doesn't trigger configured sys.no-input-default or sys.no-input-[1-6] event handlers after a period of user inactivity.

Cause

The sys.no-input-* event handlers rely on no speech timeout and voice activity detection (VAD), which are specific to streaming audio and telephony channels. Text-based channels (such as web chat or mobile messaging) don't have server-side idle timers; they only trigger sys.no-input if the client explicitly sends an empty text string (such as the user pressing Enter with no text).

Resolution

To implement an inactivity timeout in a text-based chat application:

  1. Track user idle time on the client side in your web or mobile chat frontend.
  2. If the user doesn't respond within the specified timeout period, have the client application call the detectIntent API method with a custom event (such as USER_INACTIVITY).
  3. In your agent flow or page, add an event handler for the custom event to respond to the inactive user.

Agent simulator doesn't respond to DTMF keypress input

Issue

When testing an agent in the Dialogflow CX simulator, entering DTMF digits (for example, 1234#) produces no response or triggers a sys.no-match event, even though DTMF is enabled in the agent settings.

Cause

The parameter configured to capture the DTMF digits isn't marked as Required on the active page. Without a required parameter, the page doesn't enter form filling mode and doesn't listen for DTMF keypad input.

Resolution

  1. In the Dialogflow CX console, open the flow and select the page expecting DTMF input.
  2. Under Parameters, select the parameter intended to capture the DTMF input.
  3. Select the Required checkbox.
  4. In the parameter fulfillment, configure the prompt to request the DTMF digits from the user.
  5. Click Save and test the DTMF input again in the simulator.

Enabling CMEK fails with project not eligible error

Issue

When attempting to enable customer-managed encryption keys (CMEK) for a project or location in Dialogflow CX, the operation fails with an error similar to the following:

Project PROJECT_NUMBER is not eligible for CMEK, failed eligibility checker: DialogflowEligibilityChecker... Project already has resources in the following table(s): LocationSettings

Cause

Once any Dialogflow CX agent or LocationSettings resource is initialized in a project and region using default Google-owned and Google-managed encryption keys, that project and region combination can't retroactively be converted to CMEK.

Resolution

To use CMEK for your agents:

  1. Create a new Google Cloud project.
  2. Initialize CMEK in the selected region in the new project before creating any Dialogflow CX agents or resources in that region.
  3. Export your existing agents from the original project and restore them into the new CMEK-enabled project.

Agent latency on initial request after idle period (cold start)

Issue

When sending a request to a Dialogflow CX agent that hasn't received traffic for an extended period, the first request experiences noticeably higher latency, while subsequent requests process quickly.

Cause

When an agent receives no conversational traffic for an extended duration, the serving infrastructure offloads the agent's NLU model from active serving instances. When the next request arrives, the model must be initialized and loaded into memory across serving tasks (warm-up phase), causing initial latency.

Resolution

  1. In production environments with intermittent traffic, configure an automated monitoring job or Cloud Scheduler task to send periodic keep-alive requests (approximately 10–20 requests per hour) to keep the agent model warm.
  2. If your agent uses webhooks hosted on serverless platforms like Cloud Run, set the minimum number of instances to at least 1 (min-instances = 1) to eliminate container cold start delays on the webhook backend.

Design for controlled conversations

Build your agent with clearly defined conversation paths. Ensure that the agent can request the information needed to fulfill user requirements. Avoid overly broad conversational scope, which can lead to unpredictable behavior.

Analyze logs

The inputs and outputs of playbooks, tools, and data stores are captured in the logs. Use the collected conversation IDs to follow the chain of calls and identify where execution went wrong.

Experiment with prompting

If a specific set of instructions isn't working as expected, try rewording it. Alternatively, you can use Gemini to generate prompts (meta-prompting). This iterative approach can help to find the optimal phrasing for your use case.

Provide complete information to support

When opening a support case with Cloud Support, include the relevant conversation IDs and logs collected during your investigation. This information is critical for debugging issues efficiently.