Troubleshooting IFS AI Connectivity¶

Preliminary Diagnostics¶

When isolating an issue with IFS AI connectivity, establish the current state of the environment before proceeding with specific troubleshooting steps.

Newly Provisioned Environments

Test the connection with machine learning services (Read about machine learning configurations here).
Capture the machine learning and IFS Copilot logs (Read about machine learning logs here).
Validate the tenant capabilities.
Consult the Error Code Reference section below for immediate resolutions to known deployment errors.

Established Environments For environments which are operational, where AI features previously functioned normally, prioritize isolating the exact onset time of the failure. Document the specific input data and parameters provided to the feature immediately preceding the error.

Installation Verification¶

Unsuccessful Installations

Verify that configuration parameters match the Connecting to IFS AI guidelines. Ensure all parameter names and values are exact.
Confirm the environment has unrestricted network access to the IFS AI Platform and the Access Studio endpoint. Verify that no firewall rules or network blockers are impeding traffic.

Successful Installations Verify the creation and population of the nxs-access-studio secret. Ensure it contains valid entries for the following:

access-studio-nonce
access-studio-refresh-token
access-studio-tenant-uri

Service Authentication Troubleshooting¶

Access Studio Credential Retrieval Failures

If a service encounters errors while accessing Access Studio for client credentials:

Restart pods associated with IFS AI service access (ifsapp-chat, ifsapp-xdiv, ifsapp-connect, ifsapp-odata) immediately following the middle-tier installation.
Verify that the nexus-uri in ifscloud-values.yaml is correctly set for the regional deployment.

Reference: Error Codes and Resolutions¶

Use this reference to identify and resolve frequently occurring issues. If an issue requires escalation, please contact Support.

Error	Description	Resolution
400 Bad Request	Requests are being routed to a tenant that has been offboarded.	Contact support and provide the relevant pod logs.
401 Unauthorized	The environment's JWT tokens cannot be verified.	Contact support to troubleshoot and repair token verification.
403 Forbidden / Tenant Not Authorized	The tenant is either suspended or lacks the required AI capabilities.	Validate the tenant information. Please contact IFS Support to provision the tenant and activate capabilities or to add a new capability for the first time.
413 Payload Too Large / Token Limit Exceeded	The request exceeds the 25,000 maximum input token limit. This frequently occurs with PDF recipes, as high page counts and tables trigger rate limitations.	Verify the request token count using the OpenAI Platform tokenizer to ensure inputs remain under the threshold.
500 Error Fetching IFS AI Access Token	IFS AI token validation has failed, or a middle-tier deletion has occurred.	Contact Support and provide the relevant pod logs.
no-protocol: not-set	The machine learning service is improperly configured within the environment, or a required environment variable is failing to load at runtime.	Standard Deployments: Please contact IFS Support to provision the tenant with the correct ML configuration. Remote Deployments: Verify the nxsUri configuration in the ifscloud-values.yaml file aligns with the Connecting to IFS AI guidelines. Ensure the entry exists, matches the expected protocol format, and is correctly picked up by the deployment. Restart the pods to apply any necessary corrections.
Cannot Describe a Dataframe Without Columns	Data cleaning removed all columns for categorical/numerical data. The clean_data_rules threshold in the ML recipe dictates the maximum allowed percentage of missing values per column. Columns exceeding this limit are automatically dropped.	Increase the threshold to 15-30%. If the error persists, the dataset lacks sufficient data for processing.
Unsupported LLM	The configured LLM (e.g., gpt-5.2) is not currently available or supported in the IFS AI environment, resulting in an InternalServerError during the inference request.	Please contact IFS Support for IFS Copilot cases, or other AI use cases.