phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-08-15 22:18:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

kill useless troubleshooting section

Browse source
This commit is contained in:
Ashwin Bharambe 2025-08-14 17:16:14 -07:00
parent 1e2bbd08da
commit 3d86bffdd4
3 changed files with 22 additions and 141 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/source/contributing/index.md
View file

@ -31,5 +31,4 @@ For developers who need deeper understanding of the testing system internals:
:maxdepth: 1
testing/record-replay
testing/troubleshooting
```

140
docs/source/contributing/testing/troubleshooting.md
View file

@ -1,140 +0,0 @@
# Common Testing Issues
The most frequent problems when working with Llama Stack's testing system.
## Missing Recordings
**Error:**
```
RuntimeError: No recorded response found for request hash: abc123def456
Endpoint: /v1/chat/completions
Model: meta-llama/Llama-3.1-8B-Instruct
```
**Cause:** You're running a test that needs an API interaction that hasn't been recorded yet.
**Solution:**
```bash
# Record the missing interaction
LLAMA_STACK_TEST_INFERENCE_MODE=record \
LLAMA_STACK_TEST_RECORDING_DIR=./recordings \
pytest tests/integration/inference/test_your_test.py
```
## API Key Issues
**Error:**
```
HTTP 401: Invalid API key
```
**Cause:** Missing or invalid API key for the provider you're testing.
**Solution:**
```bash
# Set the required API key
export FIREWORKS_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here
# Verify it's set
echo $FIREWORKS_API_KEY
```
## Model Not Found
**Error:**
```
Model 'meta-llama/Llama-3.1-8B-Instruct' not found
```
**Cause:** Model isn't available with the current provider or hasn't been downloaded locally.
**For local providers (Ollama):**
```bash
# Download the model
ollama pull llama3.2:3b
# Use the downloaded model
pytest tests/integration/ --text-model=llama3.2:3b
```
**For remote providers:**
```bash
# Check what models are available
uv run llama stack list-models
# Use an available model
pytest tests/integration/ --text-model=available-model-id
```
## Server Connection Issues
**Error:**
```
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=5001)
```
**Cause:** Server isn't running or is on a different port.
**Solution:**
```bash
# Check if server is running
curl http://localhost:5001/v1/health
# Start server manually
llama stack run --template starter --port 5001
# Or use auto-server with custom port
pytest tests/integration/ --stack-config=server:starter:8322
```
## Request Hash Mismatches
**Problem:** Tests worked before but now fail with "No recorded response found" even though you didn't change the test.
**Cause:** Request parameters changed slightly (different whitespace, float precision, etc.). The hashing is intentionally precise.
**Solution:**
```bash
# Check what's in your recordings
sqlite3 recordings/index.sqlite "SELECT endpoint, model FROM recordings;"
# Re-record if the request legitimately changed
rm recordings/responses/old_hash.json
LLAMA_STACK_TEST_INFERENCE_MODE=record pytest tests/integration/your_test.py
```
## No Tests Collected
**Error:**
```
collected 0 items
```
**Cause:** No models specified for tests that require model fixtures.
**Solution:**
```bash
# Specify required models
pytest tests/integration/inference/ --text-model=llama3.2:3b
pytest tests/integration/embedding/ --embedding-model=all-MiniLM-L6-v2
```
## Getting Help
When reporting issues, include:
```bash
# Environment info
uv run python --version
uv run python -c "import llama_stack; print(llama_stack.__version__)"
# Test command that failed
pytest tests/integration/your_test.py -v
# Stack configuration
echo $LLAMA_STACK_TEST_INFERENCE_MODE
ls -la recordings/
```
Most issues are solved by re-recording interactions or checking API keys/model availability.