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

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 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:

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:

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 creates directories using file.IsNotExistMkDir. Verify the target directory exists and has correct permissions:

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 or query the kernel directly:

mount | grep /mnt/myshare

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

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:

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 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:

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 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:

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:

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:

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 or adjust the detection endpoint in 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:

# 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 – Core mount/unmount wrappers and config management.
• service/connections.go – SMB/CIFS specific logic (MountSmaba, UnmountSmaba).
• pkg/utils/httper/drive.go – HTTP client communicating with the mount daemon.
• pkg/utils/network_detection.go – Network health check implementation.
• 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}