MosisService/portal/internal/web/docs/troubleshooting.md

# Troubleshooting

Solutions for common issues when developing Mosis apps.

## Build Errors

### "Invalid manifest: missing required field"

Your `manifest.json` is missing a required field.

**Solution:** Check these required fields:
```json
{
  "id": "com.example.app",
  "name": "App Name",
  "version": "1.0.0",
  "version_code": 1,
  "entry": "assets/main.rml",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "icons": {
    "128": "icon.png"
  }
}
```

### "Invalid package ID format"

Package IDs must follow reverse domain notation.

**Valid:**
- `com.example.myapp`
- `com.yourname.calculator`
- `io.github.user.app`

**Invalid:**
- `myapp` (needs domain prefix)
- `Com.Example.App` (must be lowercase)
- `com..app` (no double dots)
- `com.app.` (can't end with dot)

### "Entry point not found"

The `entry` file specified in manifest doesn't exist.

**Solution:** Verify the path:
```json
"entry": "assets/main.rml"
```

Check that `assets/main.rml` exists relative to your manifest file.

### "Icon not found"

An icon file specified in manifest doesn't exist.

**Solution:**
1. Check file paths are correct
2. Ensure files exist
3. Use forward slashes in paths

```json
"icons": {
  "128": "icons/icon-128.png"
}
```

### "Package too large"

Package exceeds the 10MB limit.

**Solutions:**
- Compress images (use TGA or optimized PNG)
- Remove unused assets
- Move large files to external CDN
- Check for accidentally included files

## Runtime Errors

### "attempt to index nil value"

You're accessing a property on a nil variable.

**Common causes:**

1. **Element not found:**
```lua
-- Bad
local elem = document:GetElementById("typo")
elem.inner_rml = "Hello"  -- Error: elem is nil

-- Good
local elem = document:GetElementById("correct-id")
if elem then
    elem.inner_rml = "Hello"
end
```

2. **Table key doesn't exist:**
```lua
-- Bad
local data = json.decode(response.body)
print(data.user.name)  -- Error if user is nil

-- Good
if data and data.user then
    print(data.user.name)
end
```

### "attempt to call nil value"

You're calling a function that doesn't exist.

**Common causes:**

1. **Typo in function name:**
```lua
-- Bad: navigateto (lowercase t)
navigateto("settings")

-- Good
navigateTo("settings")
```

2. **Missing permission:**
```lua
-- Error if 'network' permission not declared
http.get(url, callback)
```

### "Permission denied"

You're using an API without the required permission.

**Solution:** Add permission to manifest:
```json
"permissions": ["storage", "network"]
```

### "Network request failed"

HTTP request couldn't complete.

**Common causes:**

1. **No network permission:**
```json
"permissions": ["network"]
```

2. **Invalid URL:**
```lua
-- Bad: missing protocol
http.get("api.example.com/data", callback)

-- Good
http.get("https://api.example.com/data", callback)
```

3. **HTTP not allowed (HTTPS only):**
```lua
-- Bad
http.get("http://example.com/data", callback)

-- Good
http.get("https://example.com/data", callback)
```

4. **CORS error:** The server doesn't allow cross-origin requests. Contact the API provider or use a CORS proxy.

### "Storage quota exceeded"

You've exceeded the 5MB storage limit.

**Solution:**
- Clear unnecessary data: `storage.clear()`
- Use selective removal: `storage.remove("large-key")`
- Store only essential data
- Consider using network storage for large data

## UI Issues

### Element not displaying

**Check:**

1. **Display not set to none:**
```css
/* Element might be hidden */
.element {
    display: none;  /* Remove this */
}
```

2. **Size is zero:**
```css
.element {
    width: 0;   /* Add dimensions */
    height: 0;
}
```

3. **Element is off-screen:**
```css
.element {
    position: absolute;
    left: -1000dp;  /* Move to visible area */
}
```

4. **Z-index issues:**
```css
.element {
    z-index: 1;  /* Bring to front */
}
```

### Click events not working

**Check:**

1. **Function exists:**
```xml
<button onclick="handleClick()">Click</button>
```
```lua
-- Make sure function is defined
function handleClick()
    print("Clicked!")
end
```

2. **Element is overlapped:**
Another element might be blocking clicks. Check z-index and position.

3. **Element has pointer-events: none:**
```css
.element {
    /* Remove this */
    pointer-events: none;
}
```

### Styles not applying

**Check:**

1. **Stylesheet is linked:**
```xml
<head>
    <link type="text/rcss" href="styles.rcss"/>
</head>
```

2. **Selector is correct:**
```css
/* Class selector needs dot */
.my-class { }

/* ID selector needs hash */
#my-id { }

/* Tag selector has no prefix */
button { }
```

3. **Specificity issues:**
More specific selectors override less specific ones:
```css
/* Less specific */
button { color: blue; }

/* More specific - wins */
.btn.primary { color: red; }
```

4. **Units are correct:**
```css
/* Use dp units */
padding: 12dp;

/* Not px on mobile */
padding: 12px;  /* May not work correctly */
```

### Layout breaks on different screens

**Solutions:**

1. **Use dp units instead of px:**
```css
padding: 16dp;  /* Scales properly */
```

2. **Use flexbox:**
```css
.container {
    display: flex;
    flex-direction: column;
}
```

3. **Use percentage widths:**
```css
.card {
    width: 90%;
    max-width: 400dp;
}
```

### Text is cut off

**Solutions:**

1. **Allow wrapping:**
```css
.text {
    word-break: break-word;
}
```

2. **Add overflow scrolling:**
```css
.container {
    overflow: auto;
}
```

3. **Use ellipsis (if supported):**
```css
.text {
    text-overflow: ellipsis;
    overflow: hidden;
    white-space: nowrap;
}
```

## Designer Issues

### Hot reload not working

**Solutions:**

1. **Save the file** - Changes only reload on save
2. **Check file is in watch path**
3. **Restart designer** - Sometimes needed after many changes
4. **Check for syntax errors** - Invalid files may not reload

### Designer crashes on startup

**Solutions:**

1. **Check file paths:**
```bash
# Make sure path exists
mosis-designer.exe ../assets/main.rml
```

2. **Try a simple file first:**
```xml
<rml>
<head><title>Test</title></head>
<body><p>Hello</p></body>
</rml>
```

3. **Check for missing assets:**
Images or fonts that don't exist can cause crashes.

4. **Update graphics drivers:**
The designer uses OpenGL which requires up-to-date drivers.

### Rendering looks different on device

**Common causes:**

1. **Font differences** - Ensure fonts are bundled
2. **DPI scaling** - Use dp units consistently
3. **Color profiles** - Use standard sRGB colors

## Submission Issues

### "Version code must be higher"

Each new version needs a higher version_code.

**Solution:**
```json
{
  "version": "1.0.1",
  "version_code": 2  // Increment from previous
}
```

### "Signature verification failed"

Your package signature is invalid.

**Solutions:**

1. **Rebuild the package:**
```bash
mosis build
```

2. **Check signing key is registered:**
```bash
mosis keys list
```

3. **Re-register your key if needed:**
```bash
mosis keys register ~/.mosis/keys/production.pub
```

### "Review rejected"

Check the rejection reason in your dashboard. Common issues:

| Reason | Solution |
|--------|----------|
| Inappropriate content | Remove violating content |
| Misleading description | Update description to match functionality |
| Crashes on launch | Fix startup errors |
| Missing privacy policy | Add privacy policy for data-collecting apps |
| Impersonation | Don't copy other apps |

## Getting More Help

### Check Logs

**Designer logs:**
```bash
mosis-designer.exe app.rml --log debug.log
```

**Lua errors:**
```lua
-- Add error handling
local success, err = pcall(function()
    -- Your code
end)
if not success then
    print("Error:", err)
end
```

### Search Issues

Check if others have encountered the same issue:
- Developer forum
- GitHub issues
- Stack Overflow (tag: mosis)

### Contact Support

If you're still stuck:
1. Gather error messages and logs
2. Create minimal reproduction case
3. Submit through developer portal support

## See Also

- [FAQ](faq.md) - Frequently asked questions
- [Lua API Reference](api/lua-api.md) - API documentation
- [UI Design Guide](guides/ui-design.md) - Styling reference