decaporg / decaporg/decap-cms

Provide context for API error messages

Open
#2,827 1 comment 7 reactions 0 assignees View on GitHub
area: api area: error-handling area: extensions/backends pinned
Dominant language
JavaScript
Stars
19.4k
Forks
3.1k
Avg merge
1d 14h
Merged PRs (30d)
9

Description

Related to #1693

**Is your feature request related to a problem? Please describe.**

The CMS passes along error messages from the individual backends, resulting in some pretty cryptic notifications. It would be nice to provide some context or instructions on how to deal with these errors, since the different ways to resolve them are often pretty straightforward.

**Describe the solution you'd like**

The error messages shouldn't disappear without being explicitly dismissed by the user. They should give a clear description as to why they occur, as well a way to resolve them. There is a bunch of different API errors:

___

```
API_ERROR: {"message":"404 File Not Found"}
```

As far as I know there are two scenarios that cause this error:
- The collection `folder` or `file` property is missing a value (a dedicated file or folder, can't be blank or root). The file or folder should be relative to root (so `src/posts` for example).
- There are subfolders within the collection folder

___

```
API_ERROR: Not Found
```

- The media library folder is missing, or the value of the media library property within `config.yml` isn't correct.

___

```
Failed to load entries: API_ERROR: Not Found
```

- Git Gateway is not enabled: Enable Git Gateway from the Netlify Identity settings or refresh the token
- There aren't any entries for a given collection. Not sure if we should throw this error at all actually.
___

```
Failed to load entry: API_ERROR: Not Found
```
- The collection `folder` or `file` property is missing a value (a dedicated file or folder, can't be blank or root). The file or folder should be relative to root (so `src/posts` for example).
- There aren't any entries for a given collection.
___

```
Failed to persist entry: API_ERROR: Not Found
```
- The org account needs to grant access to your Netlify CMS instance: https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/requesting-organization-approval-for-oauth-apps
___
```
Failed to persist entry: API_ERROR: Reference update failed
```

- You're using the editorial workflow but already have a branch called `cms`. This error is fixed by removing the `cms` branch from the repo.
___

Not really an API error but pretty easy to resolve:
```
Failed to load settings from /.netlify/identity
```
- Netlify Identity isn't enabled
- `config.yml` has git-gateway as a backend on a site that isn't hosted on Netlify

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.