Workspaces and Collections

Resolving workspace file issues

Fix a workspace that's read-only or can't be found because of problems with its files.

Overview

Relay reads a workspace from the files in its folder. When some of those files can't be read, the workspace becomes read-only: you can still see and send its requests, but Relay won't change anything until the files are fixed, so it never saves over work you'd want to keep. When Relay can't read the workspace at all, the workspace is unavailable.

The workspace menu marks a read-only workspace with a lock and an unavailable one with a warning triangle.

Find the files that can't be read

A read-only workspace shows a banner, such as "2 files in Payments API can't be read", at the top of the sidebar. The banner also appears in the request editor, the Workspaces window and Collection Settings.

Click the banner to see each file and what's wrong with it:

MessageWhat it means
has unresolved merge conflictsThe file contains Git conflict markers such as <<<<<<<.
isn't valid JSONThe file isn't well-formed JSON.
is missing idThe document has no id key.
is missing, followed by a keyA required key is absent.
has an invalid, followed by a keyA value has the wrong type or form.
can't be read, followed by a reasonThe document can't be read for another reason.
has the same id as, followed by a fileTwo documents in the workspace share an id.
has the same id as an item in another workspace or a draftThe id is already used outside this workspace, often because the folder was copied.
has no collection.jsonA directory in collections is missing its collection document.
has no folder.jsonA directory inside a collection is missing its folder document.

Click the magnifying glass beside a file to show it in Finder, or click Show Folder in Finder to open the workspace's folder.

Work with a read-only workspace

While a workspace is read-only:

  • You can select its requests and send them as they were loaded.
  • You can't edit its requests, collections, folders, environments, variables, authentication, scripts or settings. The sidebar's commands that would change them are dimmed, and you can't drag its items.
  • You can still edit its cookies, and your drafts and history aren't affected.

Fix the files

Open each listed file in a text editor and fix the problem. For a merge conflict, resolve it the way you would for any other file in the repository, then save. For a duplicate id, give one of the documents a new UUID, or remove the copy you don't need.

Relay watches the folder. As soon as the files can all be read, it reloads the workspace and the banner goes away.

Recover an unavailable workspace

A workspace is unavailable when Relay can't read it at all, because:

  • Its folder can't be found, for example because you moved, renamed or deleted it.
  • Its relay-workspace.json is missing or can't be read.
  • It was saved by a newer version of Relay.
  • Its folder now holds a different workspace.

In place of its collections, the sidebar explains why the workspace is unavailable and offers these buttons:

  • Locate…: Choose the workspace's folder where it is now. This appears for a workspace you keep in a folder of your own.
  • Show in Finder: Show the workspace's folder in Relay's storage. This appears for a workspace Relay stores.
  • Remove from Relay: Stop showing a workspace you keep in a folder. Its folder and files stay where they are.
  • Delete: Move a workspace that Relay stores to the Trash. This can't be undone in Relay.

A workspace saved by a newer version of Relay opens normally once you update Relay. Relay always keeps at least one workspace, so you can't remove or delete the last one.

See Also