Documentation

Troubleshooting the Asset Library CLI

Solve common issues with sign-in, organization access, plug-in installation, and importing or packaging assets with the Asset Library CLI.
Read time 4 minutesLast updated a day ago

Solve common issues that can occur when you set up the Asset Library CLI or import, download, or package assets.
When a command doesn't work as expected, run
unity assetlibrary doctor
first. The
doctor
command checks the plug-in installation, sign-in, organization, access, and connection to the Asset Library service.

Sign-in fails or the session expires

Asset Library commands fail because the Unity CLI isn't signed in to your Unity account.

Symptoms

A command reports that you aren't signed in, or that your session expired.

Resolution

To sign in again, follow these steps:
  1. Sign in to the Unity CLI:
    unity auth login
  2. Confirm that the setup works:
    unity assetlibrary doctor

Wrong organization or no access

Commands that check ownership, such as
import
, use the Unity CLI's active organization. If the organization is wrong, the command can't confirm that you own the asset.

Symptoms

A command reports that you don't have access to an asset, or uses a different organization than you expect.

Resolution

To use the correct organization, follow these steps:
  1. Check which organization the Unity CLI uses:
    unity cloud org current
  2. Change the active organization:
    unity cloud org set-default <id-or-name>
    Alternatively, to use a different organization for a single command, add
    --org <orgId>
    to that command.

Import stops because of a file conflict

The
import
command doesn't overwrite project files that differ from the asset's files.

Symptoms

The import stops before it writes any files, and the error message contains the following text:
would overwrite

Cause

A file in your project differs from the asset's file at the same location. For example, you edited the file, or another asset uses the same path.

Resolution

To resolve the conflict, follow these steps:
  1. To find out which files conflict, run the same command with
    --dry-run
    .
  2. Decide whether to keep your project files. To replace them with the asset's files, run the command again with
    --force
    .
Warning
The
--force
option replaces the conflicting files in your project. Back up any files that you want to keep before you use it.

Import fails because a render pipeline isn't specified

Symptoms

The import fails, and the error message contains the following text:
choose one with --render-pipeline

Cause

The asset has a separate variant for each render pipeline, and the command doesn't know which variant to import.

Resolution

Add the
--render-pipeline
option with
urp
,
hdrp
, or
builtin
. The error message lists the variants that the asset includes. For example:
unity assetlibrary import <assetId> --render-pipeline urp

Import fails because the folder isn't a Unity project

Symptoms

The import fails, and the error message contains the following text:
is not inside a Unity project

Cause

The
import
command runs in a folder that isn't inside a Unity project. A Unity project folder contains both an
Assets
folder and a
ProjectSettings/ProjectVersion.txt
file.

Resolution

Do one of the following:
  • Run the command from inside a Unity project folder.
  • Add
    --project <path>
    to specify the Unity project.

Asset Library commands aren't recognized

Symptoms

The Unity CLI reports that
unity assetlibrary
isn't a recognized command.

Cause

The Asset Library CLI isn't installed, or your Unity CLI version doesn't support it.

Resolution

To make the command available, follow these steps:
  1. Check that your Unity CLI version is 1.0.0 or later:
    unity version
  2. If your version is earlier than 1.0.0, update the Unity CLI. For the update steps, refer to Update the Unity CLI.
  3. Install the plug-in:
    unity plugin install assetlibrary

Package imports with a trust warning

Symptoms

When you import a .unitypackage file that you built with
unity assetlibrary package
, the Unity Editor shows a trust warning and asks you to select Import Anyway.

Cause

The Unity Editor shows the trust warning for one of the following reasons:
  • The user who imports the package isn't a member of the organization that the package is signed for.
  • Signing failed when you built the package.

Resolution

Do one of the following, depending on the cause:
  • Build the package again with
    --org
    set to the importing user's organization.
  • Check the
    package
    command output for a signing warning. In JSON output,
    data.signed: false
    means the package is unsigned. Build the package again.

Additional resources