Troubleshoot a data source that won't connect or scan

This page applies to customer sites: the organisation data portals on Team Cloud, Business Cloud, Enterprise plans. It helps when a connected data source shows Error, finds no data, or finds less than you expect.

Start with the scan log

1. Check the source’s status

   In the Data Manager, open the Sources tab. Each source shows a status: Scanning, OK, Error, No scans, or Stale. Stale means the last scan finished more than 30 days ago. Scan it again to refresh it.

2. Open the Logs tab and select the latest scan

   Open the source and select Logs. Select the most recent scan, then read Log Output. The log is the best clue to what went wrong, and it’s what Koordinates support will ask for. The messages for each type of source are below.

3. Fix the problem, then scan again

   Select Scan on the source. A new scan starts with the changes you’ve made. To change connection details, select Settings, then the Connection tab. See Scan and manage connected data sources.

If the source is inside your own network, check that you’re connecting through a Data Gateway. Koordinates can’t reach a database, network share or ArcGIS server that’s only open inside your network.

PostgreSQL

Koordinates connects to your database to read it, and only reads. It doesn’t change anything in it. See Connect to a PostgreSQL database.

What you see in the log	What it usually means
Connection refused or timeout expired	Koordinates can’t reach the host and port. Check the host name, the port (the default is 5432), and that your firewall allows connections from outside your network. If the database is inside your network, connect through a Data Gateway.
password authentication failed for user	The user name or password is wrong. Edit the source’s connection and enter the password again.
no pg_hba.conf entry for host	The database’s access rules (pg_hba.conf) don’t allow this user, database or address to connect, or they don’t allow the type of connection Koordinates uses. Ask your database administrator to allow it.
An SSL or certificate error	See SSL and certificates.
Table contains geometries with different projections	A table has geometries in more than one coordinate system, and can’t be read as one dataset. Make the geometries consistent in the database, or use a view that does.

SSL and certificates

You can’t change the SSL setting in the Connect to PostgreSQL Source window. By default, Koordinates connects with SSL (encryption):

• It requires SSL but doesn’t check the server’s certificate.
• For hosts that end in .rds.amazonaws.com or .postgres.database.azure.com, it also checks the certificate. It accepts certificates signed by public certificate authorities and by the AWS RDS root certificates. This check doesn’t apply to connections through a Data Gateway.

Koordinates doesn’t support custom or private certificate authorities. If you’re connecting to an Amazon RDS or Azure database and the scan fails with a certificate error, check that the server’s certificate is one of those. If your database doesn’t support SSL, or its certificate comes from your own certificate authority, contact Koordinates support.

Which tables are found

• Koordinates scans the Schemas you entered when you connected. If you left it blank, it scans only the schemas on the database user’s default search path. Enter * to scan every schema. information_schema and pg_catalog are always skipped.
• Spatial tables are found only if the database has PostGIS, and only if the user can read (SELECT) them. Give the database user SELECT access to every table or view you want to see.
• A table with a geometry column appears as the table name followed by the geometry column in brackets.
• The tables named metadata, metadata_external and metadata_reference aren’t scanned as data.
• Koordinates detects that a table has changed from its columns and from the insert, update and delete counts that PostgreSQL keeps for it. So scan after the data has changed.

Amazon S3

See Connect to an Amazon S3 data source, or the AWS Web Console method. Check these in order.

1. The role can be assumed

   If the log says an error occurred while trying to assume the role, the role’s ARN is wrong or its trust policy is misconfigured. Check that the role’s name starts with koordinates-s3-access, that the trust policy lists the Koordinates account ID shown in the guide, and that it requires your site’s external ID, copied exactly from the Connect to Amazon S3 Source window. Don’t require MFA on the role.

2. The bucket name is right

   If the log says Not Found, check the bucket name for typos. Enter only the bucket name, not an s3:// address or a path.

3. The role has the two permissions it needs

   The role needs s3:ListBucket on the bucket (the resource ends at the bucket name, for example arn:aws:s3:::my-example-bucket) and s3:GetObject on the objects in it (the resource ends with /*). A common mistake is to give only s3:GetObject, or to put /* on the s3:ListBucket resource. Without s3:ListBucket, the log says Unable to read any files from this bucket! Likely this is a permissions issue.

4. The prefix matches

   If you entered a Prefix, Koordinates scans only objects whose key starts with it and ignores the rest. Check these:

   • A prefix is matched as text, not as a folder. maps also matches maps-old/file.tif. To scan only the folder maps, enter maps/.
   • A prefix must not start with / and must not contain //. Don’t use characters such as ` \ { } < > ^ [ ] # % " ~ | & @ $ = ; : , ?.
   • A prefix can also point straight at one file.
   • If your policy allows s3:ListBucket only for a prefix (using an s3:prefix condition), enter the same prefix in the source. Otherwise the listing is denied.
   • If nothing matches, the log says Unable to read any files from this bucket! The bucket/prefix is empty. or Unable to find data - invalid prefix or scan root.

5. The file names are scannable

   Koordinates skips objects whose keys contain .. as a folder name, and the log says Skipping bad key. Folder marker objects (keys ending in /) are ignored.

CIFS network shares

CIFS (SMB) sources are available on Enterprise plans, by request. See Connect to a CIFS network share. A share inside your network is reached through a Data Gateway.

If the share can’t be mounted, the log says only Mount failed!. Check the host and port (the default port is 445), the exact share name, and the user name and password. Check that the Data Gateway is selected if the share is on your internal network, and that the account can read the share. If it still fails, raise a ticket and include the log.

ArcGIS REST API

See Connect an ArcGIS REST API source.

• Enter the address of the ArcGIS REST services endpoint, which usually ends in /rest/services. When you connect, Koordinates also tries some common variations of the address you give. You can include a folder path to scan only that folder.
• If a layer is served by both a FeatureServer and a MapServer, Koordinates uses the FeatureServer one, and the log says Skipping ... also served by its FeatureServer for the other.
• Layers with no features are ignored, and the log says (No features, ignoring).
• If a layer can’t be read, the log may show a warning with the reason, and the other layers are still scanned. Check the log for a layer that’s missing from the results.
• A server that’s only open inside your network can’t be scanned from outside. Use a Data Gateway.

WFS

See Connect to a WFS service.

• Use the address of the WFS service. If the service offers it, Koordinates uses WFS version 2.0.0 or 1.1.0.
• The log shows which kind of server Koordinates thinks it is talking to, such as GeoServer or Esri ArcGIS Server, or says the server is unknown. An unknown server can still work.
• A message such as Failed to scrape or Unknown error scanning followed by a layer name means that layer couldn’t be read. The scan carries on with the other layers.
• If the service needs a user name and password, choose Username & Password and enter them.

When to contact support

Raise a ticket with the name of the source, the time of the scan, and the text of the Log Output. Remove passwords, access keys and API keys from anything you send.