Troubleshooting

Common issues and solutions when integrating with Lunar Stream.

Quick Links

Issue Type	Link
API Errors	Error Codes
Common Questions	FAQ

Common Issues

Authentication Failed

Symptom: 401 Unauthorized response

Solutions:

1. Verify API Key is correct and not expired
2. Check header name is ls-api-key (not Authorization)
3. Ensure no extra spaces in the API Key

# Correct
curl -H "ls-api-key: ls_proj_v1_xxx..."

# Wrong
curl -H "Authorization: Bearer ls_proj_v1_xxx..."

Stream Not Playing

Symptom: HLS player shows error or blank screen

Checklist:

1. Check stream status is STARTED
2. Verify HLS URL is accessible
3. Check CORS settings if playing from browser
4. Try different CDN URL from hlsSources

// Check stream status first
const response = await fetch(`${API_URL}/livestreams/stream-info/${streamKey}`);
const { data } = await response.json();
console.log('Stream status:', data.status); // Should be "STARTED"

RTMP Connection Refused

Symptom: OBS/FFmpeg cannot connect to RTMP server

Solutions:

1. Verify RTMP URL format: rtmp://host/live/streamKey?pushToken=xxx
2. Check push token is not expired
3. Ensure port 1935 is not blocked by firewall
4. Generate new push token if expired

Push Token Expired

Symptom: Stream disconnects after some time

Solution: Generate a new push token before expiration:

const tokenData = await lunarStream.generatePushToken(streamKey, 7200);
// Update broadcaster with new RTMP URL

No Media Servers Available

Symptom: Empty array from /media-servers/available

Solutions:

1. Contact Lunar Stream admin to check server status
2. Verify project ID is correct
3. Check if your project has access to media servers

Debugging Tips

Enable Verbose Logging

// Node.js with axios
const axios = require('axios');

axios.interceptors.request.use(request => {
  console.log('Request:', request.method, request.url);
  return request;
});

axios.interceptors.response.use(
  response => {
    console.log('Response:', response.status, response.data);
    return response;
  },
  error => {
    console.error('Error:', error.response?.status, error.response?.data);
    return Promise.reject(error);
  }
);

Test API Connectivity

# Test API is reachable
curl -v https://api.lunarstream.kozow.com/api/v1/health

# Test authentication
curl -v -H "ls-api-key: YOUR_API_KEY" \
  "https://api.lunarstream.kozow.com/api/v1/media-servers/available?projectId=YOUR_PROJECT_ID"

Check HLS Stream

# Test HLS URL is accessible
curl -I "https://stream.lunarstream.kozow.com/live/STREAM_KEY/hls.m3u8"

# Download and check manifest
curl "https://stream.lunarstream.kozow.com/live/STREAM_KEY/hls.m3u8"

Getting Help

If you cannot resolve the issue:

1. Collect error messages and logs
2. Note the stream key and timestamp
3. Contact Lunar Stream support with details