Documentationbreadcrumb arrow Pluginsbreadcrumb arrow Salesforce data sourcebreadcrumb arrow Troubleshooting

Troubleshoot Salesforce data source issues

This document provides guidance for troubleshooting common issues when configuring and using the Salesforce data source in Grafana.

Before you begin

Before investigating specific errors, verify that the data source health check passes:

  1. Click Connections in the left-side menu.
  2. Click Data sources and select your Salesforce data source.
  3. Click Save & test.
  4. Confirm you see a success message.

If the health check fails, start with the Configuration errors or Authentication errors sections.

Authentication errors

Authentication errors occur when there are issues with your credentials, Connected App configuration, or access permissions.

Invalid username, password, security token; or user locked out

This error indicates that your authentication credentials are incorrect or the user account is locked.

Possible causes:

  • Incorrect username or password
  • Invalid or expired security token
  • User account is locked due to too many failed login attempts
  • Password has been reset without updating the security token

Solutions:

  1. Verify that the username is the full email address used to log in to Salesforce (e.g., user@company.com).
  2. Confirm the password is correct and hasn’t expired.
  3. Reset your security token in Salesforce and update it in Grafana. Security tokens are regenerated when passwords are reset.
  4. Check if the user account is locked in Salesforce Setup under Users > Users.

Invalid client credentials

This error indicates that the Consumer Key or Consumer Secret from your Connected App are incorrect.

Possible causes:

  • Consumer Key or Consumer Secret was copied incorrectly
  • Connected App was deleted or recreated
  • Connected App credentials were regenerated

Solutions:

  1. Navigate to your Connected App in Salesforce Setup under Apps > App Manager.
  2. Click View next to your Connected App, then Manage Consumer Details.
  3. Copy the Consumer Key and Consumer Secret carefully, ensuring no extra whitespace.
  4. Update the credentials in your Grafana data source configuration.

JWT authentication failures

JWT authentication errors occur when there are issues with the certificate, private key, or Connected App JWT settings.

Error messages:

  • invalid_grant - The JWT assertion is invalid
  • invalid_client - Client authentication failed
  • user hasn't approved this consumer - User pre-authorization is missing

Possible causes:

  • Certificate not uploaded to the Connected App
  • Private key doesn’t match the uploaded certificate
  • User hasn’t pre-authorized the Connected App
  • Certificate has expired
  • Incorrect Callback URL for JWT flow

Solutions:

  1. Verify the certificate is uploaded to your Connected App under Enable Use digital signatures.
  2. Ensure the private key in Grafana matches the certificate uploaded to Salesforce.
  3. Pre-authorize the Connected App for your user:
    • Navigate to Setup > Manage Connected Apps > Edit Policies for your app.
    • Set Permitted Users to “Admin approved users are pre-authorized”.
    • Add the appropriate profiles or permission sets.
  4. Verify the Callback URL is set to sfdc://oauth/jwt/success.
  5. Check that your certificate hasn’t expired and regenerate if necessary.

Refresh token has been revoked

This error indicates that the OAuth refresh token has been invalidated.

Possible causes:

  • User revoked access to the Connected App
  • Administrator revoked all OAuth tokens
  • Connected App settings were changed

Solutions:

  1. Re-enter your credentials in the Grafana data source configuration.
  2. Click Save & test to generate a new authentication session.
  3. Check if the Connected App’s refresh token policy has changed.

Connection errors

Connection errors occur when Grafana cannot establish a connection to Salesforce.

Connection timeout

The connection to Salesforce took too long to establish.

Possible causes:

  • Network connectivity issues
  • Firewall blocking the connection
  • Salesforce service is experiencing issues

Solutions:

  1. Verify network connectivity from the Grafana server to Salesforce.
  2. Ensure your firewall allows outbound connections to *.salesforce.com and *.force.com on port 443.
  3. Check the Salesforce Trust Status page for any ongoing incidents.
  4. If using Private data source connect (PDC), verify the PDC agent is running and connected.

Request blocked by organization’s IP restrictions

Salesforce can restrict API access to specific IP ranges.

Possible causes:

  • Your Grafana server’s IP address is not in the trusted IP ranges
  • Login IP ranges are configured for the user’s profile

Solutions:

  1. Add your Grafana server’s IP address to the trusted IP ranges in Salesforce Setup under Security > Network Access.
  2. Alternatively, configure the user’s profile to allow login from any IP address.
  3. If using Grafana Cloud, add the Grafana Cloud IP addresses to your trusted ranges.

Configuration errors

Configuration errors occur when the data source or Connected App is not set up correctly.

OAuth settings not enabled

The Connected App doesn’t have OAuth enabled.

Solution:

  1. Edit your Connected App in Salesforce Setup.
  2. Under API (Enable OAuth Settings), check Enable OAuth Settings.
  3. Configure the required OAuth scopes:
    • For Credentials authentication: Access and manage your data (api)
    • For JWT authentication: Access and manage your data (api) and Perform requests on your behalf at any time

Missing OAuth scopes

The Connected App doesn’t have the required OAuth scopes configured.

Error messages:

  • insufficient_access - User lacks required permissions
  • API_DISABLED_FOR_ORG - API access is not enabled

Solutions:

  1. Edit your Connected App and verify the following scopes are selected:
    • Access and manage your data (api) - Required for all authentication methods
    • Perform requests on your behalf at any time (refresh_token, offline_access) - Required for JWT authentication
  2. If you receive API_DISABLED_FOR_ORG, contact your Salesforce administrator to enable API access for your organization.

Sandbox vs Production environment mismatch

You’re trying to connect to a Sandbox environment but have the wrong environment selected, or vice versa.

Solutions:

  1. In the Grafana data source configuration, click the Environment drop-down.
  2. Select the correct environment:
    • Production for production Salesforce instances
    • Sandbox for sandbox or test instances
  3. Sandbox environments use test.salesforce.com for authentication, while production uses login.salesforce.com.

Query errors

Query errors occur when there are issues with your SOQL queries.

MALFORMED_QUERY

Your SOQL query contains syntax errors.

Example error:

MALFORMED_QUERY: unexpected token: 'FROM'

Possible causes:

  • Missing or extra commas in the SELECT clause
  • Typo in field or object names
  • Invalid operators in the WHERE clause

Solutions:

  1. Validate your SOQL query syntax. Refer to SOQL SELECT Syntax.
  2. Use the Query Builder mode to construct valid queries before switching to SOQL Editor mode.
  3. Check for common issues:
    • Fields should be comma-separated: SELECT Name, Amount, CloseDate
    • String values should use single quotes: WHERE Status = 'Open'
    • Dates should use the format: WHERE CreatedDate > 2024-01-01T00:00:00Z

INVALID_FIELD

The specified field doesn’t exist on the queried object.

Example error:

INVALID_FIELD: No such column 'InvalidFieldName' on entity 'Opportunity'

Solutions:

  1. Verify the field name exists on the Salesforce object. Use the SOQL Editor’s autocomplete feature (Ctrl+Space) to see available fields.
  2. Check if the field is a custom field and uses the correct suffix (e.g., Custom_Field__c).
  3. Ensure the user has field-level security access to the field.

INVALID_TYPE

The specified object doesn’t exist or is not accessible.

Example error:

INVALID_TYPE: sObject type 'CustomObject__c' is not supported

Solutions:

  1. Verify the object name is correct and includes __c for custom objects.
  2. Check if the user has access to the object in their profile or permission sets.
  3. Ensure the object is not in a managed package that hasn’t been installed.

No rows returned / No data

Your query executes successfully but returns no results.

Possible causes:

  • The time range filter excludes all data
  • Filters are too restrictive
  • Data doesn’t exist for the queried criteria

Solutions:

  1. Expand the Grafana time range to verify data exists.
  2. Remove or broaden your WHERE clause filters.
  3. Test the query directly in Salesforce using Developer Console or Workbench.
  4. Verify you’re using the correct macros for time filtering ($__timeFrom, $__timeTo).

Query results exceed limits

Salesforce limits the number of records returned by SOQL queries.

Solutions:

  1. Add a LIMIT clause to your query to restrict results (e.g., LIMIT 2000).
  2. Use more specific filters in the WHERE clause to reduce the result set.
  3. Consider using aggregate queries with GROUP BY instead of returning all records.
  4. The default limit in Query Builder mode is 100 rows. Adjust this value as needed.

Filter and Query Builder errors

Errors specific to the Query Builder mode.

Complex filter logic not supported

The Query Builder doesn’t support complex filter combinations.

Cause: Queries with both AND and OR statements, or nested filters, will fail in Query Builder mode.

Solution:

Switch to SOQL Editor mode to write complex queries manually:

soql 
SELECT Name, Amount FROM Opportunity
WHERE (Status = 'Open' AND Amount > 1000) OR (Status = 'Closed' AND CloseDate > LAST_MONTH)

Reports mode errors

Errors specific to the Reports query mode.

Report not found

The specified report doesn’t exist or isn’t accessible.

Solutions:

  1. Verify the report exists in Salesforce and hasn’t been deleted.
  2. Check that the user has permission to view the report.
  3. Ensure the report folder is shared with the user.

Report timeout

Large reports may take too long to execute.

Solutions:

  1. Simplify the report by reducing filters or groupings.
  2. Consider creating a summary report instead of a detailed report.
  3. Use SOQL mode with specific filters instead of running large reports.

Known limitations

The following are known limitations when using the Salesforce data source.

Unsupported query formats

Only SOQL queries are supported. The following are not supported:

  • SOSL (Salesforce Object Search Language)
  • SAQL (Salesforce Analytics Query Language)
  • Einstein Analytics queries

Unsupported Salesforce products

  • Salesforce Commerce Cloud (SFCC) is not supported.

Ad-hoc filters

Ad-hoc filters are not supported by the Salesforce data source.

Complex filter logic in Query Builder

When using the Query Builder, queries with mixed AND/OR logic or nested filters require switching to SOQL mode.

Debugging tips

Use these techniques to gather more information when diagnosing issues.

Enable query inspector

To view the executed query and response:

  1. Open your dashboard panel.
  2. Click the panel title and select Inspect > Query.
  3. Review the request and response for error details.

Check Grafana server logs

For detailed error information:

  1. Access your Grafana server logs.
  2. Search for salesforce to find relevant log entries.
  3. Look for error messages and stack traces that provide more context.

Test queries in Salesforce

Validate your SOQL queries directly in Salesforce:

  1. Log in to Salesforce.
  2. Open Developer Console from the gear icon.
  3. Click Debug > Open Execute Anonymous Window.
  4. Or use the Query Editor tab to run SOQL queries.
  5. Confirm the query works before using it in Grafana.

Verify API access

Test that API access is working with your credentials:

  1. Ensure your Connected App has the correct OAuth scopes.
  2. Verify the user profile has API Enabled permission.
  3. Check that your organization hasn’t exceeded API request limits in Salesforce Setup under System Overview.

Get additional help

If you continue to experience issues after following this troubleshooting guide:

  1. Check the Salesforce documentation for platform-specific guidance.

  2. Review the Grafana community forums for similar issues.

  3. Contact Grafana Support if you’re a Grafana Enterprise, Cloud Pro, or Cloud Advanced user.

  4. When reporting issues, include:

    • Grafana version
    • Salesforce edition (e.g., Enterprise, Professional)
    • Authentication method (Credentials or JWT)
    • Error messages (redact sensitive information like tokens and passwords)
    • Steps to reproduce
    • Relevant configuration (redact credentials)