Asset and File Troubleshooting

This page covers issues encountered when managing assets, uploading and downloading files, working with asset versions, and creating asset links through the VamsCLI.

Asset Operations

Asset or Database Not Found

The CLI reports that an asset or database cannot be located.

Symptoms:

Asset Not Found: Asset '...' not found in database '...'
Database Not Found: Database '...' not found

Cause:

The asset or database ID is incorrect, the resource is archived, or the calling user lacks access to it.

Resolution:

List the available resources to confirm the correct ID:

vamscli database list
vamscli assets list -d my-database

If an asset appears to be missing, it may be archived. Include archived assets in the lookup:

vamscli assets get my-asset -d my-database --show-archived
vamscli assets list -d my-database --show-archived

If the resource exists but is still inaccessible, confirm your role has permissions on it, or contact your administrator.

Asset Already Exists

vamscli assets create fails because an asset with the same identity already exists.

Symptoms:

Asset Already Exists

Resolution:

Asset IDs are generated by VAMS and cannot be supplied during creation. To change an existing asset, use vamscli assets update instead of recreating it. Use vamscli assets list -d my-database to review the current assets.

note

Passing assetId in --json-input to vamscli assets create is rejected. Remove the field and let VAMS assign the ID.

File Uploads

File Extension Validation Error

An upload is rejected because the target database restricts which file types it accepts.

Symptoms:

File Extension Validation Error: Database has file extension restrictions: ...

Cause:

The database is configured with restrictFileUploadsToExtensions, which limits uploads to a defined set of extensions. All files are validated before upload, and every violation is reported at once. Validation is case-insensitive.

Resolution:

Inspect the allowed extensions on the database:
```
vamscli database get -d my-database
```
Upload only files with permitted extensions, or convert files to an allowed format first.

An administrator can change or remove the restriction:

# Restrict to specific extensions
vamscli database update -d my-database --restrict-file-uploads-to-extensions ".glb,.gltf"

# Remove the restriction entirely
vamscli database update -d my-database --clear-file-extensions

note

Asset preview uploads (--asset-preview) and preview auxiliary files (those containing .previewFile. in the name) skip the database's restriction list, but are validated against the allowed preview image extensions (.png, .jpg, .jpeg, .svg, .gif) instead. For a .previewFile. name the extension is everything after the marker, so model.gltf.previewFile.p.png is read as .p.png and refused. A database with no restriction configured accepts all other file types.

Preview File Rejected

An --asset-preview upload fails validation.

Symptoms:

Preview file ... exceeds maximum size of 5MB
Preview file ... has unsupported extension

Cause:

Asset preview images must be no larger than 5 MB and must use one of the supported extensions: .png, .jpg, .jpeg, .svg, .gif.

Resolution:

Compress the image to under 5 MB or convert it to a supported format, then re-run the upload:

vamscli file upload -d my-database -a my-asset --asset-preview thumbnail.jpg

Upload Fails or No Files Uploaded

An upload completes with failures, or no files are uploaded at all.

Symptoms:

File Upload Error
Upload completed with some failures

Cause:

Network instability, throttling, or transient backend errors during multipart upload.

Resolution:

Confirm the source files exist and are readable.

Increase resilience and reduce concurrency on unstable connections:

vamscli file upload -d my-database -a my-asset model.glb \
  --retry-attempts 5 --parallel-uploads 5

Use --force-skip to continue past parts that fail after all retries, or split very large batches into smaller uploads.

tip

The CLI automatically chunks large files and splits large batches into multiple upload sequences. This is handled for you and reported in the upload summary.

Files Do Not Appear After Upload

The upload succeeds, but the files are not yet visible in the asset listing.

Symptoms:

Asynchronous Processing notice after a successful upload
Files are missing from vamscli file list shortly after upload

Cause:

Large files undergo separate asynchronous processing on the backend after the upload completes, so they may take longer to appear. No action is required.

Resolution:

Allow processing to finish, then re-check the asset:

vamscli file list -d my-database -a my-asset

Processing time scales with file size. If files do not appear after an extended period, confirm the upload returned exit code 0 and contact your administrator.

File Management

File Not Found in Asset

A file operation fails because the path cannot be found within the asset.

Symptoms:

File Not Found: File '...' not found in asset

Cause:

The file path is incorrect, the path is case-sensitive, the file is archived, or the shell rewrote the path before the CLI received it.

Resolution:

List the asset's files to confirm the exact path:

vamscli file list -d my-database -a my-asset

Include archived files if the target may have been archived:

vamscli file list -d my-database -a my-asset --include-archived

Inspect a single file, including its version history:

vamscli file info -d my-database -a my-asset -p "/model.gltf" --include-versions

On Windows, re-run the command with MSYS_NO_PATHCONV=1 if you are using Git Bash, MSYS2, or Cygwin:
```
MSYS_NO_PATHCONV=1 vamscli file info -d my-database -a my-asset -p "/model.gltf"
```

File paths within an asset are absolute and begin with /. Those shells rewrite an argument that begins with / into a Windows path before the CLI receives it, and quoting does not prevent it, so -p "/model.gltf" arrives as a local filesystem path that the asset does not contain. --source and --dest on file move and file copy are rewritten the same way, which can direct the operation at an unintended path. See Asset-relative paths on Windows on the File Commands page.

File Move or Copy Fails

vamscli file move or vamscli file copy does not complete.

Symptoms:

File Move Error or File Copy Error

Cause:

The source path is invalid, the destination conflicts with an existing file, or the destination asset or database does not exist.

Resolution:

Verify the source file exists with vamscli file info.

For cross-asset or cross-database copies, confirm the destination exists and that you have permissions on both ends:

vamscli file copy -d my-database -a my-asset \
  --source "/file.gltf" --dest "/file.gltf" \
  --dest-asset other-asset --dest-database other-db

File Delete Requires Confirmation

vamscli file delete exits without deleting.

Symptoms:

Permanent deletion requires confirmation (--confirm)

Cause:

File deletion is permanent and requires the --confirm flag as a safeguard.

Resolution:

Re-run with --confirm. To remove every file under a path, add --prefix:

vamscli file delete -d my-database -a my-asset -p "/folder/" --prefix --confirm

warning

Permanent deletion cannot be undone. To remove a file recoverably, use vamscli file archive instead.

Recovering Files

To restore archived files or roll back a file to an earlier version, work through the file's history:

# Find archived files
vamscli file list -d my-database -a my-asset --include-archived

# Restore an archived file
vamscli file unarchive -d my-database -a my-asset -p "/file.gltf"

# Review the version history
vamscli file info -d my-database -a my-asset -p "/file.gltf" --include-versions

# Revert the file to a previous version
vamscli file revert -d my-database -a my-asset -p "/file.gltf" -v version-id-123

An archived asset can be restored in full with vamscli assets unarchive, which also removes the delete markers on its files and preview.

Asset Versions

Version Not Found

A version operation references a version that does not exist.

Symptoms:

Version Not Found: Asset version '...' not found

Resolution:

List the available versions, including archived ones if necessary:

vamscli asset-version list -d my-database -a my-asset
vamscli asset-version list -d my-database -a my-asset --show-archived

Version Creation Rejected

vamscli asset-version create fails validation.

Symptoms:

Invalid Version Data: Comment is required
Cannot specify --files when --use-latest-files is true

Cause:

A comment is always required. --use-latest-files (the default) and an explicit --files list are mutually exclusive.

Resolution:

Always pass --comment. To capture the current files, rely on the default --use-latest-files. To version a specific set of file versions, pass --no-use-latest-files together with --files:

# Version the current files
vamscli asset-version create -d my-database -a my-asset --comment "New release"

# Version specific file versions
vamscli asset-version create -d my-database -a my-asset --comment "Pinned files" \
  --no-use-latest-files \
  --files '[{"relativeKey":"file.obj","versionId":"abc123","isArchived":false}]'

Skipped Files During Version or Revert Operations

A version or revert operation succeeds but lists skipped files.

Symptoms:

Skipped Files (N): ...
Version Revert Failed: Target version has no accessible files

Cause:

Some files referenced by the target version have been permanently deleted from Amazon S3 or are otherwise inaccessible.

Resolution:

This is informational; the operation still completes for the accessible files. Use vamscli asset-version get -d my-database -a my-asset -v <version> to inspect file status indicators. If a revert fails entirely, choose a different target version that still has accessible files.

Asset Links

Link Already Exists or Creates a Cycle

vamscli asset-links create is rejected.

Symptoms:

Asset Link Already Exists
Cycle Detection Error

Cause:

A relationship already connects the two assets, or the requested parentChild link would form a cycle in the hierarchy.

Resolution:

Review the existing relationships, using the tree view to visualize the hierarchy:
```
vamscli asset-links list -d my-database --asset-id my-asset --tree-view
```
Update the existing link rather than recreating it, or use the related relationship type, which is bidirectional and not subject to cycle detection.

note

The valid relationship types are related and parentChild. The --alias-id option applies only to parentChild links.

Asset Link Permission Error

A link operation fails on authorization.

Symptoms:

Permission Error: You need permissions on both assets

Cause:

Creating, updating, deleting, or listing asset links requires access to the assets involved in the relationship.

Resolution:

Confirm you have permissions on both the source and target assets with vamscli assets get, then retry. Contact your administrator if access is missing.

Downloads

Asset Not Distributable or Has No Files

vamscli assets download returns nothing to download.

Symptoms:

Asset not distributable
Asset '...' currently has no files to download

Cause:

Only distributable assets can be downloaded, and the asset must contain non-archived files.

Resolution:

Check the asset's distributable flag and contents:

vamscli assets get my-asset -d my-database
vamscli file list -d my-database -a my-asset

Mark the asset distributable if appropriate:

vamscli assets update my-asset -d my-database --distributable

Download Times Out or Fails on the Network

Downloads stall, time out, or fail mid-transfer.

Symptoms:

Download failed with status 408: Request timeout
Download failed: Network connection error

Cause:

Large files, an unstable connection, or restrictive firewall or proxy settings.

Resolution:

Increase the per-file timeout and retries, and reduce concurrency:

vamscli assets download /local/path -d my-database -a my-asset \
  --timeout 600 --retry-attempts 5 --parallel-downloads 3

Verify outbound HTTPS connectivity if failures persist.

Download Link Expired

A previously generated shareable link no longer works.

Symptoms:

Download failed with status 403: Request has expired

Cause:

Presigned download URLs are time-limited and expire 24 hours after they are generated.

Resolution:

Regenerate the links immediately before use. For automation, fetch links just before downloading:

vamscli assets download -d my-database -a my-asset --shareable-links-only

Filename Conflicts in a Flattened Download

A flattened download reports duplicate filenames.

Symptoms:

Filename conflicts detected in flattened download: ...

Cause:

--flatten-download-tree discards the folder structure, so files that share a name in different folders collide.

Resolution:

Omit --flatten-download-tree to preserve the folder hierarchy. In interactive (non-JSON) mode the CLI prompts to skip, overwrite, or rename conflicting files; in --json-output mode the download aborts so it can be re-run interactively.

Directory Synchronization

Sync Reports Changed Files But Transfers Nothing

vamscli sync file push or pull lists files under skipped_modify or skipped_delete without transferring or removing them.

Symptoms:

Skipped (modified, use --allow-modify): ...
Skipped (delete candidates, use --allow-delete): ...

Cause:

By default sync only adds missing files. Modifying or deleting files each requires its own opt-in flag.

Resolution:

Add --allow-modify to transfer changed files, and --allow-delete to remove files missing from the source side. Preview the effect first:

vamscli sync file push ./models -d my-database -a my-asset --allow-modify --allow-delete --dryrun

Confirmation Required for Deletions

A sync with delete flags fails before doing anything.

Symptoms:

Permanently deleting files in VAMS requires the --confirm flag.
Deleting local files requires the --confirm flag.

Cause:

Destructive sync operations are double-gated. On push, --permanent-delete requires --confirm (archiving with --allow-delete alone does not). On pull, --allow-delete always requires --confirm because local deletion cannot be undone.

Resolution:

Add --confirm after reviewing a --dryrun plan, or omit the delete flags to leave files in place. Archived VAMS files remain recoverable:

vamscli file unarchive -d my-database -a my-asset -p "/removed-file.glb"

Files Never Appear in the Sync Plan

Certain local files are always reported as ignored or unsupported.

Symptoms:

Ignored by patterns: N file(s)
Unsupported (previews or no file extension): N file(s)

Cause:

Files matching .vamsignore patterns are excluded from both sides of the comparison. Preview companion files (.previewFile.*) and files without a file extension cannot be synced because the file APIs do not list or accept them as regular files.

Resolution:

Review the .vamsignore file in the sync directory (or the file passed via --ignore-file), or bypass patterns entirely with --no-ignore. Rename extension-less files to include an extension before pushing.

Every Sync Re-Transfers the Same Files

Repeated syncs keep transferring files that have not changed.

Symptoms:

The same files appear in the plan with reason newer on every run.

Cause:

Timestamp comparison relies on the local file's modified time. Tools that rewrite files without changing content (build steps, checkouts) refresh local timestamps, making files look newer than the remote copy.

Resolution:

Use --size-only to compare by size alone when timestamps are unreliable:

vamscli sync file push ./models -d my-database -a my-asset --allow-modify --size-only

Diagnostics

When a command fails for an unclear reason, re-run it with the global --verbose flag for detailed error information, API requests and responses, and per-request timing:

vamscli --verbose assets download /local/path -d my-database -a my-asset

Validate complex --json-input payloads separately before passing them to a command:

echo '{"assetName":"test"}' | python -m json.tool

Asset Operations​

Asset or Database Not Found​

Asset Already Exists​

File Uploads​

File Extension Validation Error​

Preview File Rejected​

Upload Fails or No Files Uploaded​

Files Do Not Appear After Upload​

File Management​

File Not Found in Asset​

File Move or Copy Fails​

File Delete Requires Confirmation​

Recovering Files​

Asset Versions​

Version Not Found​

Version Creation Rejected​

Skipped Files During Version or Revert Operations​

Asset Links​

Link Already Exists or Creates a Cycle​

Asset Link Permission Error​

Downloads​

Asset Not Distributable or Has No Files​

Download Times Out or Fails on the Network​

Download Link Expired​

Filename Conflicts in a Flattened Download​

Directory Synchronization​

Sync Reports Changed Files But Transfers Nothing​

Confirmation Required for Deletions​

Files Never Appear in the Sync Plan​

Every Sync Re-Transfers the Same Files​

Diagnostics​

Related Pages​

Asset Operations

Asset or Database Not Found

Asset Already Exists

File Uploads

File Extension Validation Error

Preview File Rejected

Upload Fails or No Files Uploaded

Files Do Not Appear After Upload

File Management

File Not Found in Asset

File Move or Copy Fails

File Delete Requires Confirmation

Recovering Files

Asset Versions

Version Not Found

Version Creation Rejected

Skipped Files During Version or Revert Operations

Asset Links

Link Already Exists or Creates a Cycle

Asset Link Permission Error

Downloads

Asset Not Distributable or Has No Files

Download Times Out or Fails on the Network

Download Link Expired

Filename Conflicts in a Flattened Download

Directory Synchronization

Sync Reports Changed Files But Transfers Nothing

Confirmation Required for Deletions

Files Never Appear in the Sync Plan

Every Sync Re-Transfers the Same Files

Diagnostics

Related Pages