Reports

The schema browser is empty or missing tables I know to be in the database

The tables listed in Mode’s schema browser may differ from what you expect for a number of reasons:

  • The database was recently connected or updated

    Mode’s schema browser updates roughly every 30 minutes. If you recently connected a new database, the schema browser may appear blank for up to 30 minutes. Similarly, if new tables were added to an existing database, they may not appear for up to 30 minutes. To instruct Mode to perform a schema browser refresh, click on the menu-dots-gray-press Created with Sketch. button in the upper right corner of the schema browser and click Refresh.

    New tables and databases, however, may be queried immediately regardless of whether or not they appear in the schema browser.

  • You don’t have permission to see the missing tables

    Mode connects to your database as a database user. This user, which is defined by your database, may not have access to all of the tables in your database. If you think this might be the case, try querying one of the tables that’s missing from the schema browser. If the query returns an error saying you don’t have permission to access that table, this is likely the issue.

    Resolve this issue by granting the database user access to the missing tables. These configurations are defined by the database and typically managed by database admins. These permissions cannot be changed directly in Mode.

  • Your database connection is Google BigQuery

    Updating schema information for Google’s BigQuery requires Mode to make a request to your BigQuery database. Because Google charges money per request, Mode does not automatically update the schema for BigQuery databases. To manually instruct Mode to perform a schema browser refresh, click on the menu-dots-gray-press Created with Sketch. button in the upper right corner of the schema browser and click Refresh.

Does Mode time-out long running queries or reports?

Mode will cancel any incomplete queries or report runs after a certain period of time to prevent long-running queries from degrading the performance of Mode or your database. Note that your database may be configured to time-out queries sooner than the times listed below:

Scenario Time-out after
Manual query / report run 12 hours
Scheduled run (daily / weekly / monthly) 12 hours
Scheduled run (hourly) 1 hour
Scheduled run (every 30 minutes) 30 minutes
Scheduled run (every 15 minutes) 15 minutes

Scheduled runs

My schedule didn’t run when it was supposed to. Why not?

The most recent scheduled execution may have failed. This could happen for a few reasons:

  • Your query or database schema may have changed, causing a query in the report to fail.
  • Mode lost its connection to your database.
  • One or more queries in the report took too long to run and timed out.

To see why your schedule may have failed to run:

  1. Open the report and click View Details in the header.
  2. All runs of the report will be listed on the right. Scheduled runs will say “Scheduled run by…”. Review the run history for any runs that did not complete.
  3. Hover the name of one of query name, click the menu-dots-gray-press Created with Sketch. button, and select View History…

In the Query History pane, click the failed query run. The Query Editor should display an error message that explains the failure.

If you don’t see a failed run and the scheduled run appears to have never been executed, please contact our success team for assistance.

Error messages

Sorry, this dataset is too large to display

To ensure that charts and results can render correctly in the browser, Mode limits the size of query results that can be shown. You can view and chart query results up to 15 MB.

Query results larger than 15 MB and smaller than 1 GB can be exported via CSV or accessed via the Notebook, but Mode will not display those results in the browser. In this case, Mode will display an error message suggesting an estimated number of rows to which you can limit your query.

Sorry, the results of this query are too large to retrieve from the database

Query results over 1 GB cannot be returned to Mode from a database. If your results exceed this limit, add a LIMIT statement to your query to return a smaller set of results.

Direct Connect

How do I know if my database is publicly accessible?

A database is “publicly accessible” if the server it is hosted on can be reached via any internet connection. Users aren’t required to be logged into a VPN or on a private network to access the database.

To check if your database is publicly accessible, run the following command on a computer that’s not logged into your VPN or private network. Replace your_db_host and your_db_port with the host and port of your database:

  • Linux or OSX: nc -v your_db_host your_db_port
  • Windows: telnet your_db_host your_db_port

If the connection succeeds, your database is publicly accessible. If it fails, it likely isn’t.

In some instances, however, the connection can fail because your database doesn’t allow connections from IP addresses that haven’t been added to a whitelist. If this may be the case, find your computer’s IP address and add it to your database’s IP address whitelist. Try the command above again. If it succeeds, your database is publicly accessible and can connect to Mode directly. Note that you may need to whitelist Mode’s IP addresses in your database’s configuration.

When connecting to any database, your address is in a reserved range
Could not verify connection: Address ... in reserved range.

Your database may not be publicly accessible. This article describes how to check. If your database isn’t publicly accessible, you should connect using Bridge.

Could not verify connection: com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.

This is generic MySQL error that indicates Mode can’t reach your database. There are a couple of common causes for this error:

  • Your database doesn’t allow SSL connections: Direct Connect only supports SSL connections. If SSL is disabled on your MySQL database, Direct Connect will be unable to connect. To resolve this issue, you can either allow SSL connections to your database or connect using Bridge.

  • Your MySQL database isn’t configured to allow external connections: Check the configuration file at /etc/mysql/my.cnf. If the bind_address is set to 127.0.0.1, your database will only allow connections from your local machine. To allow external connections—which is required for connecting to Mode—change the bind address to 0.0.0.0.

When connecting to Redshift, it says we’re having trouble verifying your connection
Could not verify connection: We're having trouble verifying your connection. Please check that the hostname and port are correct and that your firewall is configured to allow connections from Mode.

This is a generic error that indicates Mode can’t reach your Redshift database. There are a couple of common causes for this error:

  • Your Redshift security group or VPC security doesn’t allow connections from Mode’s IP addresses: If your Redshift is in a security group, you must configure that security group to allow connections from Mode’s IP addresses. Note that if your Redshift is in a VPC, the VPC may also be part of security group that’s distinct from the Redshift security group. This VPC security group must also allow connections from Mode. See this article about which IP addresses to whitelist, this article for how to configure security groups in your Redshift instance, and this article for more information on security settings for Redshift.

  • Use a Redshift host name rather than the IP address: Redshift host names are often formatted like this: examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com. Try using a host of this format rather than an IP address. This host can be found in the middle of the JDBC URL, which typically matches the following format: jdbc:redshift://examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439/dev.

When connecting to BigQuery, it says we couldn’t verify your connection
Could not verify connection: com.modeanalytics.jdbc.bigquery.BQSQLException: toDerInputStream rejects tag type 123

This error occurs if you try to connect with a JSON key rather than a P12 key. When completing the last step of setting up your BigQuery connection, double-check that you’re using a P12 key.

I get a connection error that says “The server does not support SSL”

This means that your database does not have SSL configured. To ensure your data remains secure, Direct Connect doesn’t support connecting unless your database allows encrypted connections. To enable SSL, please refer to your database’s website for information on how to configure TLS/SSL for your database.

If you don’t want to or can’t enable SSL, you can connect your database to Mode using Bridge. Though Bridge connections use transport encryption by default, you can disable it by clicking the green “turn off transport encryption” link when setting up Bridge.

Transport encryption

“Publicly accessible” databases aren’t databases that can be queried by anyone in the general public—nearly all “publicly accessible” databases still require passwords and encrypted connections. Instead, “publicly accessible” means that the database can be reached via any internet connection. Users aren’t required to be logged into a VPN or on a private network to access the database.

The easiest way to check if your databases is publicly accessible is to run the following command on a computer that’s not logged into your VPN or private network. Replace host and port with the host and port of your database:

nc -v host port

If the connection succeeds, your database is publicly accessible. If it fails, it likely isn’t.

In some instances, however, the connection can fail because your database doesn’t allow connections from IP addresses that haven’t been added to a whitelist. If this may be the case, find your computer’s IP address and add it to your database’s IP address whitelist. Try the command above again. If it succeeds, your database is publicly accessible and can connect to Mode directly, provided that the appropriate IP addresses are whitelisted.

Bridge

When connecting to any database, Bridge says it could not verify the connection

You may see several error messages that say Bridge could not verify the connection.

Could not verify connection: please try again.
Could not verify connection: We're having trouble verifying your connection. Please check that the hostname and port are correct and that your firewall is configured to allow connections from Mode.

This error indicates that Mode could reach your Bridge connector, but Bridge couldn’t reach your database.

You may see this error if your database credentials are invalid. As a first step, check the credentials and try again. Note that if your database doesn’t have a password, entering any password should fix this error.

If you’re sure the credentials are correct, these errors can also occur when Bridge is installed on a machine that can’t access your database. Importantly, this error occurs from the perspective of the machine running Bridge, not necessarily from your computer or from Mode’s servers. Most commonly, this error occurred when your database is accessible only to computers inside a VPN. If you installed Bridge on a computer outside your VPN or if the computer is not currently logged into the VPN, Bridge won’t be able to connect to your database.

You can test if the machine running Bridge has access to the database by running this command on the machine running Bridge:

  • Linux or OSX: nc -v your_db_host your_db_port
  • Windows: telnet your_db_host your_db_port

If the command succeeds, the computer has access to the database. You can contact Mode support for further assistance.

If the command fails, the computer running Bridge doesn’t have access to the database. To fix this, you should either install Bridge on a machine that has access or adjust your network settings so that the machine running Bridge has access to your database.

When connecting to any database, Bridge says it could not verify the connection and that there was a problem connecting to your Bridge Connector
Could not verify connection: There was a problem connecting to your Bridge Connector.

This error indicates that Mode couldn’t reach your Bridge connector.

First, check if Bridge is running with the command listed below.

  • Linux or OSX: ps aux | grep mode-bridge
  • Windows: Look in Service Manager to see if Bridge is running.

If Bridge is not running, restart the Bridge application.

If Bridge is running, Mode may not not be able to reach Bridge because the ports that Bridge connects over are closed. Bridge connects to Mode over outbound port 8444. You can confirm that the port is open for Bridge by running these commands on the computer running Bridge

  • For Linux or OSX:

    nc -v cat-gin-flower.bridge.modeanalytics.com 8444
  • Windows:

    telnet cat-gin-flower.bridge.modeanalytics.com 8444

If these commands fail, you must open the outbound port on your network and on the computer running Bridge.

If the port is open and you still see this error, your Bridge config file may not match what Bridge is looking for. If you have made manual changes to the config file, either revert your custom changes and try connecting again or contact Mode support for additional help.

When installing Bridge on Windows, Bridge is unable to write to config.json
Unable to write to ...\config.json

This error typically occurs when you attempt to install Bridge without the proper permissions. To resolve, open an instance of PowerShell with elevated privileges (Run as Administrator) and use that instance to install Bridge.

How can I replace an existing Bridge connection?

To replace an existing Bridge connection, first remove the existing Bridge from Mode.

  1. Click on your avatar in the upper left.
  2. Select Settings from the dropdown.
  3. Click on Bridges under the appropriate organization name.
  4. Remove the Bridge from that page.

Next, add the new database.

  1. Click on your avatar in the upper left.
  2. Select Connect a database from the dropdown
  3. Click on the Database on a Private Network tab
  4. Select the appropriate database type.

The next page should prompt you to install Bridge. Because you already have Bridge installed, skip to the final step that asks you to run mode-bridge setup. On the machine where you’re running Bridge, add -replace to the command listed and run the entire command. The new command should look like this:

mode-bridge-setup -replace -init BIG_BLOG

Finally, restart the Bridge application.

White-Label Embeds

General

Why does my embed show a Mode-branded border?

Only Internal Embeds include a Mode-branded border. A White-Label Embed should not include a Mode-branded border. If you are attempting to implement a White-Label Embed and the iframe includes a Mode-branded border when it is accessed, it is not implemented correctly and the embed is falling back to an Internal Embed when accessed.

To test this, attempt to access the embed while either logged out of Mode or using a private browser mode (e.g., incognito mode in Google Chrome). When you access the embed without an active Mode session, it should return an error message that you can use to troubleshoot.

Error messages

Report cannot be displayed - Embed request signature cannot be verified. Please check signing method

Troubleshoot White-Label Embeds

This error indicates there is a problem with the signature that is included in the signed embed URL. If you see this error, check that you are correctly generating the URL signature. An embed may return this error for any of the following reasons:

  • The timestamp value in the URL query string in the future or is more than 10 seconds in the past.
  • The signed embed URL is different in any way from the URL that was used to generate the signature (including changes to parameter values included in the query string), with the exception of the addition of the signature field and corresponding value to the query string.
  • The API token is deleted or otherwise invalidated.
  • The field-value pairs in the URL query string were not in alphabetical order when the signature was generated.
Report cannot be displayed - Embed parameters cannot be verified

Troubleshoot White-Label Embeds

A valid signed embed URL must include a value for each of a report’s defined parameters in the URL’s query string. Check embed URL the following:

  • Ensure the entire URL (including the query string with any parameter values) is URL encoded.
  • Ensure the signature was generated with an encoded URL.
  • A URL encoded value is included for every parameter defined in the report.
  • Each parameter is included in the format &param_[PARAM_NAME]=[PARAM_VALUE], where [PARAM_NAME] is the exact name used in the parameter definition.
  • Ensure the URL query string contains references only to parameters that are defined in the report.
Report cannot be displayed - This request has expired. Please try again

Troubleshoot White-Label Embeds

A signed embed URL is only valid for 10 seconds. If you attempt to access a signed embed URL after 10 seconds, you will receive this error. (Note that the 10 second expiration only applies to initial requests for the report; results won’t be removed after 10 seconds).

Report not found - You might not have permission to view this report

Troubleshoot White-Label Embeds

Normally, this is a result of an error in the embed URL other than a parameter error or an incorrect signature. This error may occur when:

  • Ensure White-Label Embedding has been enabled for the report.
  • The timestamp value in the URL and signature generation is not a positive integer.
  • You are not using a valid API token or the user account tied to that token does not have access to the report.
  • The URL path does not point to a valid report or report run.

White-Label Embed viewers may also receive this error when they try to view the embed but the underlying report’s creator is no longer an active member of the Mode organization containing the report. To resolve this, please do any of the following:

  • Re-invite the report’s creator/owner to the organization.
  • Have an active member clone the report and revise the White-Label Embed URL in your host application to point to this new report.

Last updated May 17, 2018