Firmware Generation Failed

OceanRemote fails to generate firmware code. The "Generate Code" button returns an error, or the page times out. This guide covers token expiry, configuration issues, browser problems, WiFi credential errors, and server-side failures.

Last updated: April 22, 2026 | 8 min read

Symptoms

• Clicking "Generate Code" shows error message or nothing happens
• Page returns "500 Internal Server Error"
• Browser console shows JavaScript errors
• Generation takes too long then times out
• Error message: "Registration token generation failed"
• Form validation errors on WiFi credentials or relay names
• Firmware generation works on one browser but not another

Common Causes

1. Invalid WiFi Credentials SSID or password contains special characters that break JSON encoding
2. Missing Required Fields Board type not selected, relay names empty, or sensor configuration incomplete
3. Session Expired Login session expired while filling out form
4. Browser Extension Interference Ad blockers, password managers, or security extensions blocking API calls
5. Rate Limiting Exceeded Too many generation attempts in short period
6. Server Overload High traffic causing temporary unavailability
7. Invalid Token in URL Direct link to generation page with expired or invalid parameters

Firmware Generation Process Flow

1. User fills configuration form
         
         
2. Form validation 
         
          Validation fails  Show error, highlight fields
         
         
3. POST request to /api/generate-code/
         
          401 Unauthorized  Session expired, redirect to login
          400 Bad Request  Invalid form data
          429 Too Many Requests  Rate limit exceeded
          500 Internal Server Error  Server error
         
         
4. Server generates registration token 
         
         
5. Server creates firmware code from template
         
         
6. Returns JSON response with firmware code
         
         
7. Browser displays code in textarea or download

Step-by-Step Fixes

1. Check All Required Fields

Missing fields prevent generation:

• Board Type: Must select ESP32, ESP8266 D1 Mini, ESP8266 D1 Large, or Pico W
• WiFi SSID: Cannot be empty
• WiFi Password: Cannot be empty
• Relay Names: All 5 relay names must be filled
• Sensor Type: Must select DHT22, DS18B20, NTC 10k, or None
• Check for red borders around required fields

2. Avoid Special Characters in WiFi Credentials

Special characters can break JSON encoding:

//  Problematic characters
// SSID: "My Home WiFi "   parentheses and spaces
// Password: "pass&word!@#$%"      special symbols

//  Safe characters
// Use letters , numbers , spaces, hyphens, underscores
// Avoid: & < > " ' / \ @ # $ % ^ * ( ) [ ] { } | ~ `

3. Check Browser Console for Errors

Open browser developer tools to see detailed errors:

• Chrome/Edge: F12 Console tab
• Firefox: F12 Console tab
• Safari: Cmd+Option+C Console tab
• Look for red error messages
• Check Network tab for failed API calls to /api/generate-code/

4. Disable Browser Extensions

Ad blockers and security extensions can block API calls:

• Temporarily disable ad blockers
• Disable privacy extensions
• Disable password managers that auto-fill forms
• Try in incognito/private mode
• Try a different browser entirely

5. Refresh Session and Retry

Session may have expired while filling form:

• Open a new browser tab and visit dashboard
• If redirected to login, session expired
• Log in again
• Return to "Your Device" page and re-enter configuration
• Generate code again

6. Check Rate Limit Status

Too many generation attempts in short period:

• OceanRemote limits token generation per hour
• Check dashboard for rate limit message
• Wait 5-10 minutes before trying again
• If using free tier, consider upgrading for higher limits
• Check admin panel for "Token generation limit" field in user profile

7. Try Minimal Configuration

Test with simplest settings to isolate issue:

// Minimal test configuration:
// Board: ESP32 Dev Module 
// WiFi SSID: "TestNetwork" 
// WiFi Password: "password123" 
// Relay 1-5: "Relay 1", "Relay 2", "Relay 3", "Relay 4", "Relay 5"
// Sensor Type: None
//
// If this works, gradually add complexity:
// 1. Add real WiFi credentials
// 2. Add custom relay names
// 3. Add sensor configuration

API Error Codes

HTTP Code	Error	Solution
400	Invalid form data	Check all required fields, remove special characters
401	Session expired or invalid CSRF token	Refresh page, log in again
429	Rate limit exceeded	Wait 5-10 minutes, try again
500	Server-side error	Try again later, contact support if persists
403	CSRF token missing or invalid	Clear browser cache, reload page

Prevention Tips

• Use simple WiFi SSID and password for first test
• Save your configuration before generating code
• Generate code within 15 minutes of logging in
• Disable ad blockers on OceanRemote domain
• Use Chrome or Firefox for best compatibility
• Copy generated code immediately tokens expire after 24 hours
• If generation consistently fails, contact support with browser console screenshot

Related Issues

• Token Invalid or Expired
• Firmware Flash Success But No Connection
• Device Offline in Dashboard
• Session Expired Too Fast

Frequently Asked Questions

Still having generation issues? Contact Support or return to the Troubleshooting Hub.