Why does QGIS show 'Unavailable layer' or a red exclamation mark?

The project saved an absolute path to a file or database that has moved, been renamed, or is on a disconnected drive. QGIS keeps the layer entry but cannot find its source, so it flags it as unavailable until you repair the data source.

How do I make QGIS use relative paths so a project moves cleanly?

In Project Properties > General, set 'Save paths' to Relative. Keep the .qgz/.qgs and its data in the same folder tree, and the project will resolve sources relative to itself when copied or shared.

How do I repair broken data source paths in QGIS?

Right-click the layer and choose 'Repair Data Source', or use Project Properties to point to the new location. For many layers at once, the Layer > Repair / Handle Bad Layers dialog or editing paths in the project file works.

Should I store layers in a GeoPackage or loose files?

For most projects a GeoPackage consolidates many vector and raster layers, styles, and metadata into one portable .gpkg file, which is far easier to move and version than dozens of shapefiles with sidecar files. Use a database (PostGIS) for multi-user editing.

QGIS Data Source Management Guide

Short answer

A QGIS project (.qgz/.qgs) does not contain your data — it stores pointers to data sources (file paths, database connection strings, service URLs) plus styling. Data source management is keeping those pointers valid and portable: choosing relative paths so a project moves intact, consolidating loose files into a GeoPackage, configuring database and service connections cleanly, and repairing the "Unavailable layer" state when a source moves. Get this right and a project opens identically on a colleague's machine, a server, or in two years; get it wrong and every layer turns red.

How QGIS references data

When you add a layer, QGIS records a data source URI — the provider plus a path or connection string. A shapefile resolves to …/data/geology.shp; a GeoPackage layer to …/project.gpkg|layername=geology; a PostGIS layer to a dbname=… host=… table=… (geom) string; a WMS/WFS layer to a service URL with parameters. The project file is just XML (zipped, in the .qgz case) holding these URIs and the symbology. Understanding that the data lives elsewhere is the key to never being surprised by a broken link.

Relative vs absolute paths

This is the single most important setting for portability. Project Properties > General > Save paths offers Absolute or Relative:

Absolute writes full paths like /home/florian/projects/site/data/geology.shp. Move or share the project and every file path breaks.
Relative writes paths relative to the project file, e.g. ./data/geology.shp. Copy the whole folder anywhere — another drive, a colleague, a server — and the layers resolve.

Set relative paths from the start, and keep a self-contained folder: the project file at the root, data in subfolders beside it. Set this as the default in Settings > Options > General so new projects inherit it. Note that database and service connections are not paths and are unaffected — those are managed separately (below).

The Data Source Manager

The unified Data Source Manager (Ctrl+L, or the toolbar button) is where all sources are added — vector, raster, delimited text, GeoPackage, SpatiaLite, PostGIS, WMS/WMTS, WFS, XYZ tiles, virtual layers. It replaces the old per-format dialogs. Use its Browser tab and the Browser panel (docked) to inspect a source before adding it: expand a GeoPackage to see its layers, preview a PostGIS schema, or check a CSV's columns. Adding from the Browser keeps you aware of exactly which source and sub-layer you are pulling in, which prevents the common "I added the wrong shapefile" error.

Repairing unavailable layers

When a source moves, QGIS shows the layer with a red exclamation mark and "Unavailable layer". The data is not lost — only the pointer is stale. To fix:

Single layer: right-click > Repair Data Source and browse to the new location. QGIS reattaches the existing styling and field references.
Handle Bad Layers: when opening a project with several missing sources, QGIS offers a Handle Bad Layers dialog where you can repoint each one before the project finishes loading.
Bulk fixes: for a folder that moved wholesale, editing the paths directly in the .qgs XML (or unzipping the .qgz) with find-and-replace is fast — but make a backup first and prefer relative paths so this never recurs.

A repaired source must have the same schema (field names/types) the styling and joins expect, or rule-based styles and labels referencing missing fields will fail.

Consolidating into a GeoPackage

Shapefiles are fragile: each is really 4–7 sidecar files (.shp/.shx/.dbf/.prj/.cpg…), field names are capped at 10 characters, and there is no single-file portability. A GeoPackage (.gpkg) is an OGC standard SQLite container that holds many vector layers, rasters, attribute tables, styles, and metadata in one file. Benefits: one file to move, no 10-character field limit, no sidecars, and stored layer styles.

To consolidate a messy project: Processing > Package layers (native:package) writes all selected layers into one GeoPackage in one step. Per-layer, GDAL does it too:

ogr2ogr -f GPKG project.gpkg geology.shp -nln geology
ogr2ogr -f GPKG -update project.gpkg faults.shp -nln faults

After packaging, re-add the layers from the .gpkg and save the project with relative paths — now the deliverable is two files (project + GeoPackage) instead of dozens.

Database and service connections

For shared, multi-user, or large data, use PostGIS. Connections are stored in QGIS settings (and optionally exported), not in the project as paths. Good practice:

Use a read-only role for analysis projects to prevent accidental edits.
Store credentials in the QGIS Authentication database rather than embedding passwords in the URI.
Export connection definitions (Browser > right-click the connection group) so a team shares identical PostGIS/WMS endpoints.
For web services (WMS/WFS/XYZ), pin a specific layer and CRS, and remember these depend on network availability — cache or download for field use.

Worked example: making a project portable

Project Properties > General — set Save paths to Relative.
Processing > Package layers — write all vector layers to data/site.gpkg.
Remove the old shapefile layers; re-add from site.gpkg via the Browser panel.
Move any rasters into ./data/ beside the project; confirm they show relative paths.
Save as site.qgz at the folder root.
Test: copy the whole folder to /tmp, open the project there — all layers should resolve with no red marks.

Common pitfalls and why they happen

All layers red after moving the project. Absolute paths were saved. Switch to relative and repackage.
Works for you, broken for a colleague. Layers sat on a drive only you have (a network mount, a D: drive). Consolidate into a GeoPackage shipped with the project.
Styling lost after repair. The replacement source has different field names; rule-based styles and labels can't bind. Keep schemas identical when repointing.
Shapefile fields truncated. The 10-character DBF limit silently renamed fields (elevation → elevatio_1). Use GeoPackage to keep full names.
Slow project open. Live WMS/WFS or remote PostGIS layers load on open. Cache static layers locally for field or offline use.
Embedded passwords leaking via the project file. Credentials in a PostGIS URI travel with the .qgs. Use the Authentication system instead.

QA and validation

Before handing a project over, do the move test: copy the folder elsewhere and open it — zero unavailable layers is the pass condition. Open the project's Browser to confirm every layer resolves to a path inside the project tree (not an external drive). Check that GeoPackage layers carry the expected feature counts and CRS, that styles render, and that any database layers connect with the shared, exported connection rather than a personal one.

Bathyl perspective

A project that only opens on the machine that made it is not a deliverable. We default to relative paths, consolidate to GeoPackage for portable handovers, and keep PostGIS for collaborative editing — so a project we ship opens cleanly for the client, the reviewer, and us in a year's time.

QGIS Data Source Management