Why a Source Failed to Process

A Source reaches ERROR when Geobble began processing the data but could not complete the ingestion workflow.

The first step is to determine where the failure occurred.

A failed Source can result from problems such as:

an unsupported or unreadable file;
missing or unusable geometry;
an incomplete multi-file dataset;
a malformed CSV;
a PostGIS connection or table configuration problem;
a storage or processing failure.

Do not immediately upload the same input again.

Identify what failed first, correct the likely cause, then retry with a reason to expect a different result.

First: distinguish ERROR from an incomplete upload

These are different situations.

PENDING with no completed file upload

A Source can exist while the required file was never successfully attached.

That is an incomplete upload, not a processing failure.

The Source page can offer the upload control again so you can complete the transfer.

See How to Monitor Source Processing Status.

ERROR

ERROR means Geobble attempted processing and the operation did not complete successfully.

Conceptually:

Source created
      ↓
file attached / import queued
      ↓
PROCESSING
      ↓
ERROR

In this case, repeatedly waiting will not make the Source become ready.

You need to investigate the cause.

1. Open the failed Source

Open the Source that reached ERROR.

Confirm that you are looking at the correct Source, particularly if you already attempted the import more than once.

Record useful context such as:

Source title;
how it was created;
file format or PostGIS workflow;
approximate file size;
whether the upload itself completed;
when the failure occurred.

If Geobble displays a processing or failure message, read that before changing the input.

2. Identify the ingestion method

Ask:

Was this Source created from a file or from PostGIS?

The troubleshooting paths are different.

ERROR
  │
  ├── File upload
  │      ↓
  │   inspect file, geometry and format
  │
  └── PostGIS import
         ↓
      inspect connection, schema,
      table and geometry configuration

Start with the appropriate path instead of changing unrelated settings.

Troubleshooting file uploads

3. Confirm that the format is supported

The current Source upload interface accepts formats including:

GeoJSON / JSON;
ZIP;
KML / KMZ;
Shapefile;
File Geodatabase;
GeoPackage;
CSV;
GML;
DXF;
DWG.

If Geobble cannot identify or process the supplied format, ingestion can fail.

Do not assume that changing a filename extension converts the data.

For example:

data.xyz

renamed to:

data.geojson

does not make the file valid GeoJSON.

Use an appropriate GIS tool to export or convert the dataset properly.

4. Check whether the file can actually be opened

A recognised extension does not guarantee a readable dataset.

Files can be:

corrupted;
partially downloaded;
truncated;
incorrectly packaged;
exported incorrectly.

Try opening the original dataset in a trusted GIS application.

For example, confirm that you can:

load it successfully;
inspect its features;
view its attributes;
see the expected geometry.

If your GIS software cannot reliably open the dataset either, fix or re-export the file before retrying Geobble.

5. Check for geographic geometry

A Geobble geographic Source needs usable geometry.

A file containing only ordinary tabular attributes may not be enough.

For example:

facility: Hospital A · operator: Public · capacity: 120
facility: Hospital B · operator: Private · capacity: 45

contains useful information but no explicit geography.

By contrast:

facility: Hospital A · longitude: 11.5167 · latitude: 3.8667
facility: Hospital B · longitude: 9.7043 · latitude: 4.0511

contains coordinates that may allow a CSV workflow to identify geographic points.

If processing reports that no geometry was found, inspect whether the input really contains spatial information in a form that can be interpreted.

CSV files deserve particular attention

CSV is flexible, which also makes it easier to create ambiguous spatial input.

Check:

whether latitude and longitude columns exist;
whether coordinate values are numeric;
whether latitude and longitude have been reversed;
whether coordinates use a consistent convention;
whether rows contain missing coordinate values;
whether the file is actually intended to represent geographic features.

For example:

longitude = 11.5
latitude  = 3.8

is plausible for Cameroon.

But:

longitude = 3.8
latitude  = 11.5

describes a different location.

Even when ingestion succeeds, coordinate mistakes can still produce geographically incorrect results, so always inspect the ready Source afterwards.

6. Check multi-file formats

Some geospatial formats consist of more than one physical file.

A classic Shapefile can include files such as:

facilities.shp
facilities.shx
facilities.dbf
facilities.prj

These components perform different roles.

Uploading an incomplete dataset can lead to missing attributes, missing projection information, or processing failure.

When working with a multi-file dataset, keep its companion files together and provide the complete dataset in the form expected by the upload workflow.

A ZIP archive is often a practical way to keep related components together when supported.

Do not delete companion files simply because only one of them has the .shp extension.

7. Check the dataset itself, not only its filename

A file can have a supported extension and still contain content Geobble cannot use successfully.

Check for issues such as:

empty layers;
invalid geometry;
unsupported internal structures;
broken database layers;
unexpected encoding;
malformed GeoJSON;
an export that produced zero usable features.

If possible, make a clean export from the original GIS software and retry that export instead of repeatedly resubmitting the same problematic file.

8. Consider whether the dataset has multiple layers

Formats such as GeoPackage or other container formats can contain more than one layer.

Geobble can process multi-layer input and create layer-specific Sources.

That means a multi-layer dataset can have a more nuanced outcome than:

everything succeeded

or:

everything failed

Individual layers can fail while others process successfully.

If your input contains several layers, inspect the resulting Sources rather than assuming that one layer failure means every layer was lost.

For example:

regional-data.gpkg
    ├── roads          → READY
    ├── hospitals      → READY
    └── boundaries     → ERROR

In that situation, troubleshoot the failing layer specifically.

9. Check whether the failure concerns processing rather than transfer

There are at least two distinct stages:

Browser
   ↓
file upload
   ↓
storage
   ↓
geospatial ingestion
   ↓
READY

A successful upload only confirms that the file reached storage.

It does not prove that the geographic contents can be processed.

Therefore:

Upload reached 100%

does not necessarily mean:

Source ingestion succeeded.

If the Source later reaches ERROR, troubleshoot the content or ingestion stage rather than the browser transfer.

Common file-ingestion failure categories

The current ingestion workflow recognises several broad failure categories.

Unsupported format

Typical meaning:

Geobble could not process the file as a supported geographic format.

Check whether the file was correctly exported and whether its actual contents match its extension.

No geometry

Typical meaning:

Geobble could not find usable geographic geometry.

Inspect whether the dataset contains actual spatial data.

File could not be read

Typical meaning:

The file may be corrupted or otherwise unreadable by the ingestion tooling.

Try opening and re-exporting it in GIS software.

Geospatial processing failure

Typical meaning:

The underlying geographic processing step could not successfully convert the dataset.

Check the source format, layer structure, geometry and export.

Storage failure

Typical meaning:

A problem occurred while Geobble was retrieving or processing the uploaded storage object.

If the original data appears valid, retrying later may be appropriate.

If the same valid file repeatedly fails in the same way, report the problem.

Troubleshooting PostGIS imports

10. Recheck the connection string

For PostGIS, confirm that the connection string still points to the intended database.

Check:

protocol;
hostname;
port;
database;
username;
password;
TLS mode.

The supported schemes are:

postgres://
postgresql://

and TLS is required.

A connection that works locally does not necessarily mean Geobble can reach it.

11. Check network reachability

The database host must be externally reachable by Geobble under the supported network policy.

Common problems include:

private-only database hosts;
firewall restrictions;
incorrect DNS;
closed PostgreSQL port;
database access allowed only from an internal VPN;
expired or changed infrastructure.

If the hostname resolves only inside your organisation's network, Geobble cannot necessarily connect to it from the platform.

Do not solve this by indiscriminately exposing the database publicly.

Use an appropriately secured network configuration and least-privilege database credentials.

12. Check TLS configuration

PostGIS imports currently require:

sslmode=require

or:

sslmode=verify-ca

or:

sslmode=verify-full

A connection configured to disable TLS will be rejected.

If certificate verification modes are used, make sure the database's certificate configuration is valid for that mode.

13. Check the database credentials

The database user must be able to read the requested table.

A successful network connection is not the same as permission to run the required query.

Check that the user has appropriate access to:

the database;
the schema;
the table.

Prefer a dedicated read-oriented account rather than an administrative database user.

14. Check schema and table names

Geobble asks for Schema and Table separately.

For:

transport.roads

use:

Schema: transport
Table: roads

Do not enter:

Table: transport.roads

if the workflow expects the fields separately.

Also check spelling and case conventions in the actual database.

15. Check the geometry column

The configured geometry column must exist in the table.

The default:

geom

is common but not universal.

Your table might instead use:

geometry
shape
the_geom

Inspect the table schema and use the actual PostGIS geometry column.

The current import only selects rows where that geometry column is non-null.

16. Check whether the query returns usable rows

The current PostGIS import operates conceptually like:

SELECT *
FROM schema.table
WHERE geometry_column IS NOT NULL
LIMIT row_limit;

If the chosen geometry column contains no usable values, there may be little or nothing meaningful to import.

Before retrying, run an equivalent check in your own database environment.

For example:

SELECT COUNT(*)
FROM transport.roads
WHERE geom IS NOT NULL;

This helps distinguish a Geobble processing problem from a remote table that contains no spatial rows under the selected geometry column.

17. Check whether the remote table itself is valid

Try the table in your existing PostGIS or GIS workflow.

Inspect:

geometry type;
CRS;
invalid geometries;
schema;
representative rows.

If the table cannot be exported or queried successfully with standard geospatial tooling, fix the database data before retrying the Geobble import.

A failed PostGIS import does not modify the remote table

The PostGIS workflow reads from the remote table and creates a managed Geobble Source.

If import fails, Geobble does not treat that as an instruction to alter the source PostGIS table.

Conceptually:

Remote PostGIS
      │
      │ read
      ↓
Geobble import
      ↓
ERROR

The original remote database remains the source system you should inspect and correct where necessary.

Failed PostGIS processing does not consume the completed import cost

The current PostGIS processing workflow reserves credits when the operation is queued.

If the import fails before becoming ready, the processing workflow settles that reservation at zero rather than charging the completed import cost.

This does not mean repeated failed attempts are a good troubleshooting strategy.

Fix the configuration first.

18. Retry only after identifying a likely cause

A good retry has a reason.

For example:

Attempt 1:
ERROR — geometry column was "geometry"

Correction:
actual column is "geom"

Attempt 2:
retry with geometry column = "geom"

That makes sense.

This does not:

Attempt 1 → ERROR
Attempt 2 → same input → ERROR
Attempt 3 → same input → ERROR
Attempt 4 → same input → ERROR

Blind retries create clutter and make diagnosis harder.

Should I keep the failed Source?

While diagnosing the problem, keeping the failed Source can be useful because it preserves the failed attempt as a reference.

Once you understand the cause and have successfully created the intended Source, you can decide whether the failed record still has any value.

Avoid accumulating large numbers of failed Sources with names such as:

roads
roads-2
roads-new
roads-fixed
roads-final
roads-final-2

Use meaningful names for successful resources and clean up obsolete failed attempts when appropriate.

What if the same valid data keeps failing?

If you have established that:

the format is supported;
the file opens normally elsewhere;
geometry is present;
companion files are complete;
the PostGIS configuration is correct where relevant;

and the same operation still fails consistently, the problem may require platform support rather than another data correction.

When reporting the issue, provide enough diagnostic context to reproduce it without unnecessarily sharing sensitive data.

Useful information includes:

Source title;
Source URL or identifier;
approximate time of failure;
ingestion method;
file type;
approximate file size;
whether the upload completed;
whether similar files work;
the user-facing error message;
the step that consistently fails.

Do not include:

database passwords;
full PostGIS connection strings;
API credentials;
confidential dataset contents unless specifically required through an approved support process.

Example: Shapefile failure

Suppose you attempt to upload:

health_facilities.shp

but the original dataset actually consists of:

health_facilities.shp
health_facilities.shx
health_facilities.dbf
health_facilities.prj

If processing fails or the resulting dataset is incomplete, go back to the original dataset.

Keep the related components together and prepare the complete dataset in a supported form rather than repeatedly uploading only one component.

Example: CSV with no usable location

Suppose:

name,type,capacity
Hospital A,Hospital,120
Clinic B,Clinic,40

contains no geometry or coordinates.

The fact that CSV is a supported upload type does not mean every CSV can become a geographic Source.

Add or prepare appropriate geographic information first.

Example: PostGIS table configuration

Suppose your real table is:

health.facilities

with:

geometry column = location

but you configured:

Schema: public
Table: facilities
Geometry: geom

A failure is expected even though the credentials themselves may be valid.

Correct the resource identifiers:

Schema: health
Table: facilities
Geometry: location

then retry.

Troubleshooting decision tree

Source is not READY
        ↓
Is it PENDING with no completed file?
   ├── Yes → complete upload
   └── No
        ↓
Is status ERROR?
   ├── No → continue monitoring
   └── Yes
        ↓
How was it created?
   ├── File
   │    ↓
   │ supported format?
   │ readable file?
   │ geometry present?
   │ complete multi-file dataset?
   │ valid layer/data?
   │
   └── PostGIS
        ↓
     reachable host?
     valid TLS?
     credentials?
     schema/table?
     geometry column?
     usable rows?
        ↓
Correct identified cause
        ↓
Retry deliberately
        ↓
Still fails with valid input?
        ↓
Report product problem

Quick checklist

For any failed Source

I confirmed the Source is actually ERROR rather than incomplete PENDING.
I identified whether it came from a file or PostGIS.
I read any available user-facing failure information.
I avoided repeatedly retrying unchanged input.

For file uploads

The file is a supported format.
It opens successfully in GIS software.
It contains usable geographic information.
Multi-file formats include the necessary components.
Multi-layer containers have been checked layer by layer.
I tried a clean export if the original appears malformed.

For PostGIS

The host and database are correct.
The database is reachable.
TLS is configured.
Credentials can read the intended table.
Schema and table names are correct.
The geometry column exists.
The geometry column contains non-null spatial rows.
The remote table behaves correctly in my own PostGIS/GIS tools.

Before contacting support

I can reproduce the failure.
I know the approximate time and Source involved.
I can describe the failure without sending credentials.
I have not included a database password or connection string in the report.