# oss-storage-troubleshooting

Part of **OSS**

# Object Storage Service Storage Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|---------|----------|------------------|
| Invalid Endpoint Configuration | Error: `no such host` | High | Specify a valid endpoint using `-e` or correct the config file |
| Insufficient Permissions | HTTP 403 error during upload/download | High | Grant required RAM permissions or handle blocked objects |
| Sync Task Exceeds File Limit | Error: `over max sync numbers 1000000` | Medium | Reduce file count or split sync into batches when using `--delete` |

## Problem Details

### Problem 1: Invalid Endpoint Configuration

**Symptoms**
- Error message: `no such host`
- Behavior: ossutil commands fail immediately with DNS resolution errors
- Context: Occurs when the endpoint is misspelled, includes protocol prefixes (e.g., `https://`), or points to a non-existent region

**Root Cause**
The endpoint provided to ossutil is malformed or invalid. OSS endpoints must be specified as plain hostnames (e.g., `oss-cn-shanghai.aliyuncs.com`) without URL schemes or trailing slashes.

**Solution**
1. Verify the correct endpoint for your bucket’s region in the OSS console
2. Use the `-e` option to explicitly specify the endpoint:
   ```bash
   ossutil ls oss://my-bucket -e oss-cn-shanghai.aliyuncs.com
   ```
3. If using a configuration file (`~/.ossutilconfig`), ensure the `endpoint` line contains only the hostname:
   ```ini
   [Credentials]
   language=EN
   endpoint=oss-cn-shanghai.aliyuncs.com
   accessKeyId=your-key
   accessKeySecret=your-secret
   ```

**Verification**
Run a simple `ossutil ls` command. Successful output listing bucket contents confirms the endpoint is valid.

### Problem 2: Access Denied (HTTP 403)

**Symptoms**
- Error message: HTTP `403` status code
- Behavior: Upload, download, or list operations fail despite correct credentials
- Context: Common when using RAM user credentials or when objects are flagged for prohibited content

**Root Cause**
The requesting identity lacks necessary permissions on the bucket or object. Alternatively, OSS may block access to objects containing illegal or sensitive content.

**Solution**
1. For RAM users, attach a policy granting required actions (e.g., `oss:GetObject`, `oss:PutObject`, `oss:ListObjects`)
2. Check if the object is blocked by reviewing OSS violation notifications
3. If the object is intentionally stored and safe, contact support to unblock it; otherwise, delete or skip it during operations
4. Use signed URLs for temporary access if direct permission changes aren’t feasible:
   ```bash
   ossutil sign oss://my-bucket/my-object --timeout 3600
   ```

**Verification**
After updating permissions, retry the original command. A successful operation (e.g., file download completes) confirms resolution.

### Problem 3: Sync Command Fails Due to File Count Limit

**Symptoms**
- Error message: `over max sync numbers 1000000`
- Behavior: `ossutil sync` command aborts before starting transfer
- Context: Occurs only when the `--delete` option is used and the local directory contains more than 1 million files

**Root Cause**
OSS enforces a hard limit of 1,000,000 files per synchronization task when `--delete` is enabled to prevent accidental large-scale deletions.

**Solution**
1. Remove the `--delete` option if deletion of remote-only files isn’t required (no file limit applies)
2. If `--delete` is necessary, split the source directory into smaller subsets (each ≤1M files) and run multiple sync commands:
   ```bash
   # Example: sync subdirectories separately
   ossutil sync ./data/part1/ oss://my-bucket/data/part1/ --delete
   ossutil sync ./data/part2/ oss://my-bucket/data/part2/ --delete
   ```
3. Use filtering (e.g., `--include`, `--exclude`) to reduce the number of files processed in one run

**Verification**
The sync command starts transferring files without the "over max sync numbers" error. Monitor progress output to confirm ongoing operation.

## FAQ

**Q: How do I check if my ossutil configuration is valid?**  
A: Run `ossutil ls` on a known bucket. If it lists objects without errors, your endpoint, access key, and permissions are correctly configured.

**Q: Why does the `du` command incur charges?**  
A: The `ossutil du` command calls ListObjects (or ListObjectVersions if `--all-versions` is used) and ListMultipartUploads, which are billable API requests per the per-request pricing model.

**Q: What permissions are needed to sync files to a bucket?**  
A: At minimum, the identity must have `oss:PutObject`, `oss:GetObject`, `oss:ListObjects`, and `oss:DeleteObject` (if using `--delete`). Bucket ACL or RAM policies must grant these actions.

**Q: Can I resume a failed sync or transfer?**  
A: Yes, ossutil supports resumable transfers via checkpoint directories. By default, checkpoints are stored in `~/.ossutil_checkpoint/`. Do not delete this directory during active transfers.

**Q: How do I enable debug logging for ossutil?**  
A: Use the `--loglevel debug` option with any command to output detailed diagnostic information:
```bash
ossutil cp local-file oss://bucket/ --loglevel debug
```