# airec-api

Part of **AIREC**

# AIRec API Deployment Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|--------|----------|------------------|
| Internal Server Error During Deployment | Error message: `500` | High | Check `asi_service.log` for stack trace and fix underlying service issue |
| Resource Not Found During Deployment | Error message: `404` | Medium | Verify resource path in `asi_service.log` and correct configuration |
| Deployment Failure with No Clear Error | Instance fails to start or deployment hangs | High | Inspect `asi.log` and `asi_service.log` for initialization errors |

## Problem Details

### Problem 1: Internal Server Error (500) During API Deployment

**Symptoms**
- Error message: `500`
- Behavior: API deployment request returns HTTP 500; service does not become available
- Context: Occurs during or immediately after submitting a deployment configuration

**Root Cause**
- An unhandled exception occurred in the backend service during deployment processing.
- Common triggers include invalid model references, missing dependencies, or malformed configuration parameters that pass initial validation but fail at runtime.

**Solution**
1. Locate the `asi_service.log` file on the deployment host or in the logging system.
2. Search for the most recent stack trace associated with the deployment timestamp.
3. Identify the specific exception (e.g., `NullPointerException`, `FileNotFoundException`).
4. Correct the root configuration or resource issue indicated by the log.
5. Retry the deployment after applying the fix.

**Verification**
- After redeployment, confirm the API returns `200 OK` on health check endpoints.
- Ensure no new `500` errors appear in `asi_service.log` during startup.

### Problem 2: Resource Not Found (404) During Deployment

**Symptoms**
- Error message: `404`
- Behavior: Deployment fails with "resource not found"; API endpoint or asset is inaccessible
- Context: Typically occurs when referencing models, feature tables, or external services by incorrect paths

**Root Cause**
- The deployment configuration specifies a resource path (e.g., model URI, data source) that does not exist or is misspelled.
- The system validates basic syntax but cannot resolve the resource at deployment time.

**Solution**
1. Open `asi_service.log` and locate the line containing the `404` error.
2. Note the exact resource path reported as missing (e.g., `/models/rec_v1`, `feature_table:user_clicks`).
3. Cross-check this path against the actual resources registered in the AIRec console or metadata store.
4. Update the deployment configuration with the correct resource identifier.
5. Redeploy the API with the corrected configuration.

**Verification**
- Successful deployment should complete without `404` entries in logs.
- Query the deployed endpoint to confirm it loads the expected resource.

### Problem 3: Deployment Stuck or Fails Silently

**Symptoms**
- Behavior: Deployment process hangs indefinitely or terminates without clear error code
- Context: Occurs after initiating deployment via console or API; status remains "In Progress" or transitions to "Failed" with minimal detail

**Root Cause**
- Initialization failure in core components not captured in high-level status.
- Possible causes include insufficient permissions, network isolation preventing dependency fetch, or deadlock during service startup.

**Solution**
1. Access both `asi.log` (general service log) and `asi_service.log` (deployment-specific log).
2. Look for early-stage errors such as:
   - `Permission denied` when accessing storage
   - `Connection timeout` to internal metadata services
   - Repeated retry loops or thread deadlocks
3. If permission-related, ensure the deployment role has `AliyunAIRecFullAccess` or equivalent custom policy.
4. If network-related, verify VPC, security group, and endpoint configurations allow internal communication.
5. Restart the deployment agent if logs indicate a transient hang.

**Verification**
- Monitor logs during next deployment attempt for clean startup sequence.
- Confirm deployment status transitions to "Running" within expected time window (typically < 5 minutes).

## FAQ

**Q: Where are the AIRec API deployment logs located?**  
A: Deployment-related logs are written to `asi_service.log` and general service activity to `asi.log`. These files are typically found in the standard log directory of the AIRec runtime environment.

**Q: How do I enable more detailed logging for debugging deployment issues?**  
A: Increase the log level to `DEBUG` in the AIRec service configuration. This setting captures verbose initialization steps and dependency resolution attempts in `asi_service.log`.

**Q: What permissions are required to deploy an AIRec API?**  
A: The deploying identity must have permissions to read referenced models and feature tables, write to deployment metadata, and manage compute instances. The managed policy `AliyunAIRecFullAccess` includes all necessary actions.

**Q: My deployment succeeded, but the API returns errors on invocation. Is this covered here?**  
A: No—this guide focuses on deployment-time failures. Runtime inference errors are covered in separate troubleshooting guides for model serving and prediction APIs.

**Q: Can I roll back a failed deployment automatically?**  
A: AIRec does not support automatic rollback. However, you can redeploy a previous known-good configuration using its saved specification to restore service.