> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scitix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File, Image, and Development Environment Issues

> Troubleshoot image build or pull failures, file mounting issues, lost development environment content, and VSCS SSH connection failures.

This page is used to troubleshoot workload runtime environment and file access issues. First, determine whether the issue occurs during image preparation, storage mount, persistence configuration, or SSH connection.

## Image Pull or Build Failed

First confirm whether the issue occurs when the workload pulls an image or during a custom image build.

**Image Pull Failed**

1. Check the specific error message in the workload **Event**.
2. Check the image address and version, the image URLs available to the target cluster, and repository access permissions.

**Custom Image Build Failed**

1. If a build task remains queued for a long time, check the build resources, resource pool availability, personal quota, and scheduling information.
2. If the build fails, first review the **build logs** to determine whether the issue originates from the base image, Dockerfile, dependency installation, file paths, or command execution.
3. If installation with `apt` or `pip` fails, verify the package name, pinned version, package source, network, and base environment compatibility.

After correcting the confirmed configuration issues, rebuild instead of merely increasing the number of retries. For the complete procedure, see [Build Custom Images](/siverse/images/build-custom-images.md).

## Files Cannot Be Found After Mounting, or Are Read-Only

Mounting issues usually arise from inconsistencies in the source directory, the path inside the container, directory permissions, or capacity limits.

1. Confirm that the source directory actually contains the target file.
2. Verify the mapping between the source directory and the container mount path; the code should use the in-container path to access the file.
3. Check whether the Volume or directory permissions are read-only or read-write, and confirm that the directory-level permissions cover the target directory.
4. If files can be read but not written, also check the remaining Volume capacity and the user directory quota.

Datasets are typically used as read-only input. Training outputs, checkpoints, Notebooks, and temporary files should be written to a separate writable Volume.

For Volume mounting, see [Create and Use Storage Volumes](/siverse/resources/create-and-use-storage-volumes.md); for dataset mounting, see [Mount Datasets in Development Environments and Training Jobs](/siverse/datasets/mount-datasets-in-workloads.md).

## Files, Plugins, or Dependencies Missing After Restart

Container-local files and process memory are not automatically preserved after a restart. Therefore, files and dependencies in the development environment that have not been written to persistent storage may be lost after a restart, rescheduling, or recreation. Choose a storage method based on the content type:

| Content | Recommended Storage Method |
| - | - |
| Code, notebooks, results, and checkpoints | Write them to a mounted Volume, and synchronize them to the code repository when necessary. |
| Editor settings and extensions | Configure the relevant directories to use writable persistent paths, and verify before restarting that the settings have indeed been written to those paths. |
| System dependencies, toolchains, and Python packages | Save them in a custom image, or retain the Dockerfile, dependency manifest, and installation scripts. |

## VSCS SSH Cannot Connect or Still Fails After Updating the Public Key

First confirm the development environment and connection details, then check the local key:

1. Confirm that the VSCS development environment is ready and that **SSH** access was enabled when it was created.
2. Return to the current development environment details page and use the latest displayed address, port, and username. Do not reuse connection information from an old environment or previous session.
3. Confirm that the private key used by the local SSH client matches the public key stored on the platform.
4. If a `publickey` error occurs, check the local private key path, file permissions, and SSH configuration. Do not upload the private key or disable host and key verification.
5. After modifying the public key, wait approximately `1` minute, then retrieve the connection information from the details page again. If the connection still fails, continue troubleshooting based on the development environment status and SSH client error.

For key preparation, configuration creation, and connection methods, see [Using the VSCS Development Environment](/siverse/development/use-vscode-server-development-environment.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.