# How to Troubleshoot Storage Mounting Failures and Network Connection Issues in CasaOS

> Troubleshoot CasaOS storage mounting failures and network connection issues by checking logs, verifying directories, testing API endpoints, and running network detection. Fix your CasaOS problems now.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: how-to-guide
- Published: 2026-06-27

---

**You can troubleshoot CasaOS storage and network issues by checking the backend mount daemon logs in `/var/log/casaos.log`, verifying mount point directories exist, testing HTTP API endpoints at `127.0.0.1:80/mount/`, and running the network detection utility to isolate DNS or connectivity failures.**

CasaOS (IceWhaleTech/CasaOS) manages storage mounting and network connectivity through a layered architecture of specialized services. When you encounter mounting failures or network connection issues, the root cause can originate from the **Storage Service**, **Connection Service**, or **Network Detection Utility**. This guide provides the exact diagnostic steps, source file references, and API commands to identify and resolve these failures based on the actual CasaOS implementation.

## Verify the Backend Mount Daemon Is Running

CasaOS delegates kernel mount operations to a backend daemon accessed through the **HTTP Helper** (`httper`) client. The **Storage Service** in [`service/storage.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/storage.go) calls methods like `MountStorage` and `UnmountStorage`, which ultimately send HTTP POST requests to endpoints such as `/mount/mount` and `/mount/unmount`.

To verify the daemon is operational:

1. Check the daemon logs at `/var/log/casaos.log`. Search for entries containing `mount then` or `unmount then` to identify recent operations or errors.

2. Test the HTTP endpoint using curl:

```bash
curl -s http://127.0.0.1:80/mount/listmounts | jq .

```

A healthy daemon returns a JSON object with a `MountPoints` array. Connection errors or non-JSON responses indicate the daemon is down or misconfigured.

## Diagnose Specific Mount Failures

When `httper.Mount` returns an error string like `"mount failed"`, the **Storage Service** logs the response body containing the daemon's diagnostic message. Follow these steps to isolate the failure.

### Inspect API Response Messages

Manually test a mount request to capture the exact error message:

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"mountPoint":"/mnt/myshare","fs":"myshare:","mountOpt":"{\"AllowOther\": true}"}' \
     http://127.0.0.1:80/mount/mount

```

The JSON response contains a `msg` field describing the failure reason, such as "device not found", "permission denied", or "already mounted".

### Validate Mount Point Directories

The `MountStorage` function in [`service/storage.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/storage.go) creates directories using `file.IsNotExistMkDir`. Verify the target directory exists and has correct permissions:

```bash
ls -ld /mnt/myshare

```

If the directory is missing or has restrictive permissions, the daemon cannot bind the mount.

### Check for Duplicate Mounts

The daemon prevents duplicate mounts. Use the `IsMounted` helper from [`service/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file.go) or query the kernel directly:

```bash
mount | grep /mnt/myshare

```

If the mount appears in the output, the request will be ignored. Run `UnmountStorage` via the API before retrying:

```bash
curl -X POST http://127.0.0.1:80/storage/umount?mount_point=/mnt/myshare

```

### Verify Remote Storage Configuration

The `CheckAndMountByName` function retrieves mount points using `httper.GetConfigByName`. Ensure the configuration is correct:

```bash
curl http://127.0.0.1:80/config/get?name=myshare

```

Confirm the `mount_point` entry points to a writable directory.

## Troubleshoot SMB/CIFS Network Share Mounts

The **Connection Service** in [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) handles SMB/CIFS mounts through `MountSmaba` and `UnmountSmaba`. These operations wrap standard `mount.cifs` calls and share failure points with generic mounts, plus SMB-specific credential and path issues.

Common SMB failure symptoms include:

- **`mount.cifs: permission denied`** – Wrong username/password or missing `guest` option. Verify credentials in CasaOS UI under **Settings → Network Shares**.
- **`mount.cifs: No such file or directory`** – Remote path does not exist. Test with `smbclient //host/share -U user`.
- **`mount.cifs: Operation not permitted`** – Missing kernel `cifs` module or insufficient privileges. Verify with `lsmod | grep cifs` and ensure CasaOS runs with `CAP_SYS_ADMIN`.

**Example API call for SMB mounts:**

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"username":"user","password":"pass","host":"192.168.1.100","directory":"share","port":"445","mountPoint":"/mnt/smbshare"}' \
     http://127.0.0.1:80/samba/mount

```

If this returns an error, check `/var/log/casaos.log` for the exact CIFS error code.

## Resolve Network Connection Issues

CasaOS uses the **Network Detection Utility** in [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go) to evaluate connectivity through functions like `IsNetworkOk` and `GetNetworkInfo`. The utility checks DNS resolution, internet reachability, and interface status.

### Verify DNS Resolution

The utility calls `net.LookupHost`. Test DNS manually:

```bash
nslookup google.com

```

Failures here indicate unreachable DNS servers.

### Test Internet Connectivity

The detector pings `http://www.google.com/generate_204` (or a configurable endpoint). Verify with:

```bash
curl -I -s http://www.google.com/generate_204

```

### Check Interface Status

The utility enumerates interfaces using `net.Interfaces()`. Ensure at least one interface is up and has an IP address.

### Force a Network Recheck

Trigger a fresh detection cycle:

```bash
curl -X POST http://127.0.0.1:80/network/detect | jq .

```

The JSON response includes `dns_ok`, `internet_ok`, and `interfaces` fields. If this reports "offline" while your LAN functions, the issue likely involves DNS configuration or blocked outbound HTTP.

## Common Failure Scenarios and Fixes

| Scenario | Root Cause | Solution |
|----------|------------|----------|
| **Mount fails with "already mounted"** | Stale mount entry or previous unmount failure | Run `UnmountStorage` via `/v1/umount` or delete the stale mount point directory, then retry. |
| **SMB permission denied** | Incorrect credentials or read-only share | Update credentials in CasaOS UI and re-run `CheckAndMountAll`. |
| **Network detection offline but LAN works** | DNS server down or blocked HTTP | Add fallback DNS (e.g., `8.8.8.8`) to [`/etc/resolv.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/resolv.conf) or adjust the detection endpoint in [`network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/network_detection.go). |
| **Mount point disappears after reboot** | Directory created under `/tmp` or non-persistent path | Use persistent paths like `/mnt/...` and ensure `IsNotExistMkDir` runs during startup via `CheckAndMountAll`. |
| **Daemon crashes on mount request** | Missing `CAP_SYS_ADMIN` capability | Run the CasaOS container with `--cap-add=SYS_ADMIN` or enable privileged mode. |

## Essential Diagnostic Commands

Use these commands to rapidly assess system state:

```bash

# List current mounts via backend API

curl -s http://127.0.0.1:80/mount/listmounts | jq .

# Show stored remote configurations

curl -s http://127.0.0.1:80/config/list | jq .

# Mount a configured remote by name

curl -X POST http://127.0.0.1:80/storage/mountbyname?name=myshare

# Unmount a specific point

curl -X POST http://127.0.0.1:80/storage/umount?mount_point=/mnt/myshare

# Trigger full mount check (remounts missing storages)

curl -X POST http://127.0.0.1:80/storage/checkmountall

# Force network detection

curl -X POST http://127.0.0.1:80/network/detect | jq .

```

## Source Code Reference Points

If issues persist, examine these implementation files for context:

- [`service/storage.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/storage.go) – Core mount/unmount wrappers and config management.
- [`service/connections.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/connections.go) – SMB/CIFS specific logic (`MountSmaba`, `UnmountSmaba`).
- [`pkg/utils/httper/drive.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/httper/drive.go) – HTTP client communicating with the mount daemon.
- [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go) – Network health check implementation.
- [`service/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file.go) – Mount state verification (`IsMounted`).

## Summary

- Start with daemon logs at `/var/log/casaos.log` to capture exact error messages from the backend.
- Verify mount point directories exist and are not already mounted using `mount` commands or the `IsMounted` utility.
- Test API endpoints directly using curl to isolate configuration issues from UI problems.
- Check network health using the built-in detection utility to rule out DNS or connectivity failures.
- Review SMB credentials and kernel module status when dealing with network shares.

## Frequently Asked Questions

### Why does my mount fail with "already mounted" in CasaOS?

This error occurs when the kernel already has an entry for the mount point in `/proc/mounts`, but CasaOS believes it is unmounted. Run `curl -X POST http://127.0.0.1:80/storage/umount?mount_point=/mnt/yourshare` to clear the state, or manually unmount using `sudo umount /mnt/yourshare` before retrying the mount operation.

### How do I fix SMB "permission denied" errors when mounting network shares?

Verify your username and password in the CasaOS UI under **Settings → Network Shares**. Ensure the remote share grants write access to the provided account. You can test credentials independently using `smbclient //host/share -U username` before attempting the mount through CasaOS.

### Why does CasaOS report offline when my local network is working?

The **Network Detection Utility** in [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go) requires successful DNS resolution and HTTP access to `http://www.google.com/generate_204`. If your DNS server is down or outbound HTTP is blocked, the utility reports offline despite LAN connectivity. Add a reliable DNS server to [`/etc/resolv.conf`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/resolv.conf) or modify the detection endpoint in the source configuration.

### How can I verify the mount daemon is responding without using the UI?

Send a direct HTTP request to the mount list endpoint: `curl -s http://127.0.0.1:80/mount/listmounts`. If you receive a valid JSON response containing a `MountPoints` array, the daemon is running. Connection refused or timeout errors indicate the daemon has crashed or is not listening on port 80.