# UnoPim MCP Server - Troubleshooting
Common issues and solutions when using the UnoPim MCP Server.
## Table of Contents
1. [Connection Issues](#connection-issues)
2. [Authentication Problems](#authentication-problems)
3. [Tool Execution Errors](#tool-execution-errors)
4. [Product Creation Issues](#product-creation-issues)
5. [Media Upload Problems](#media-upload-problems)
6. [Performance Issues](#performance-issues)
---
## Connection Issues
### Issue: "Missing required environment variables"
**Symptoms:**
```
Error: Missing required environment variables: UNOPIM_BASE_URL, UNOPIM_CLIENT_ID...
```
**Solutions:**
1. **Check environment variables are set:**
```bash
echo $UNOPIM_BASE_URL
echo $UNOPIM_CLIENT_ID
```
2. **Load .env file:**
```bash
export $(cat .env | grep -v '^#' | xargs)
```
3. **Verify .env file exists:**
```bash
ls -la .env
cat .env # Check content is correct
```
4. **For Claude Desktop:** Check `claude_desktop_config.json` has all required env vars in the `env` object
---
### Issue: "Connection refused" or "ECONNREFUSED"
**Symptoms:**
```
Error: connect ECONNREFUSED 20.240.162.91:8000
```
**Solutions:**
1. **Verify UnoPim is accessible:**
```bash
curl http://20.240.162.91:8000/api/v1/rest/locales
```
2. **Check base URL format:**
- ✅ Correct: `http://20.240.162.91:8000`
- ❌ Wrong: `http://20.240.162.91:8000/` (trailing slash)
- ❌ Wrong: `http://20.240.162.91:8000/api/v1/rest` (includes path)
3. **Check firewall/network:**
- Verify port 8000 is open
- Check VPN connection if required
- Test from same network as MCP server
4. **Verify UnoPim service is running:**
```bash
# On UnoPim server
systemctl status unopim
docker ps | grep unopim
```
---
### Issue: "Claude Desktop not showing MCP tools"
**Symptoms:**
- Claude Desktop works but doesn't list UnoPim tools
- No MCP connection indicator in Claude Desktop
**Solutions:**
1. **Verify config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
2. **Check JSON syntax:**
```bash
# Validate JSON
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
```
3. **Verify absolute path:**
```json
{
"mcpServers": {
"unopim": {
"command": "node",
"args": ["/home/odm/AI-projects/unopim-mcp/dist/index.js"], // Must be absolute!
...
}
}
}
```
4. **Check dist folder exists:**
```bash
ls -la /home/odm/AI-projects/unopim-mcp/dist/index.js
```
5. **Restart Claude Desktop COMPLETELY:**
- Quit application (not just close window)
- Wait 5 seconds
- Launch again
6. **Check Claude Desktop logs:**
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# Look for errors related to MCP server startup
```
---
### Issue: "ngrok tunnel not working"
**Symptoms:**
- ngrok shows connected but Claude Desktop can't reach server
- Error: "Failed to connect to MCP server"
**Solutions:**
1. **Verify ngrok URL in config:**
```json
{
"mcpServers": {
"unopim": {
"url": "https://ae6ab5d4095a.ngrok-free.app/sse" // Must end with /sse
}
}
}
```
2. **Test ngrok endpoint:**
```bash
curl https://ae6ab5d4095a.ngrok-free.app/sse
```
3. **Check ngrok is pointing to correct port:**
```bash
ngrok http 3000 # Should match PORT in server
```
4. **Verify server is running on expected port:**
```bash
lsof -i :3000
netstat -an | grep 3000
```
---
## Authentication Problems
### Issue: "OAuth token failed" or "Authentication failed"
**Symptoms:**
```
Error: OAuth authentication failed: invalid_client
```
**Solutions:**
1. **Verify credentials in UnoPim Admin:**
- Go to Settings → API
- Check Client ID matches
- Regenerate Client Secret if unsure
2. **Test credentials manually:**
```bash
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-secret"
USERNAME="user@example.com"
PASSWORD="password"
CREDENTIALS=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64)
curl -X POST http://20.240.162.91:8000/oauth/token \
-H "Authorization: Basic $CREDENTIALS" \
-H "Content-Type: application/json" \
-d '{
"username": "'$USERNAME'",
"password": "'$PASSWORD'",
"grant_type": "password"
}'
```
3. **Check user has API permissions:**
- UnoPim Admin → Users
- Verify user role includes API access
4. **Verify password has no special encoding issues:**
- Try changing password to simple alphanumeric
- Test if it works with new password
---
### Issue: "Token expired" errors during operations
**Symptoms:**
```
Error: Token expired. Please re-authenticate.
```
**Solutions:**
This should auto-refresh, but if it doesn't:
1. **Check token refresh logic:**
- Default refresh: 5 minutes before expiration
- Verify server logs show refresh attempts
2. **Restart MCP server:**
```bash
# Kill existing server
pkill -f "node dist/index-http.js"
# Start fresh
./start-http.sh
```
3. **Check system time:**
```bash
date
# Ensure system time is correct (token expiry is time-based)
```
---
## Tool Execution Errors
### Issue: "Tool not found" or "Unknown tool"
**Symptoms:**
```
Error: Unknown tool: unopim_upload_product_media
```
**Solutions:**
1. **Verify server version:**
```bash
git log -1 --oneline
# Should show recent commits including media upload tools
```
2. **Rebuild project:**
```bash
npm run build
```
3. **Check tool is registered:**
```bash
# Verify tool exists in index.ts
grep -r "unopim_upload_product_media" src/index*.ts
```
4. **Restart server with fresh build:**
```bash
pkill -f "node dist"
npm run build
./start-http.sh
```
---
### Issue: "Validation error" when calling tools
**Symptoms:**
```
Error: Validation error: Required field 'sku' is missing
```
**Solutions:**
1. **Check input matches schema:**
```json
// Correct
{
"sku": "PROD-001",
"attribute": "image",
"file_url": "https://example.com/image.jpg"
}
// Wrong - missing required fields
{
"sku": "PROD-001"
}
```
2. **Review tool documentation:**
See "Available Tools Reference" for required vs optional parameters
3. **Use correct data types:**
```json
// Correct
{"limit": 100}
// Wrong
{"limit": "100"} // Should be number, not string
```
---
## Product Creation Issues
### Issue: "Name must be in channel_locale_specific"
**Symptoms:**
```
Error: Required attribute 'name' is missing for locale 'da_DK'
```
**Solutions:**
1. **Use correct value structure:**
```json
// WRONG - name in common
{
"values": {
"common": {
"name": "Product Name" // ❌
}
}
}
// CORRECT - name in channel_locale_specific
{
"values": {
"common": {
"sku": "PROD-001"
},
"channel_locale_specific": {
"default": {
"da_DK": {
"name": "Product Name" // ✅
}
}
}
}
}
```
2. **Use smart create to avoid this:**
```json
// Tool handles scoping automatically
{
"tool": "unopim_smart_create_product",
"sku": "PROD-001",
"family": "coffee_machines",
"product_data": {
"name": "Product Name", // Smart create puts it in correct place
"price": 999
}
}
```
---
### Issue: "Family not found"
**Symptoms:**
```
Error: Family 'coffee_machines' does not exist
```
**Solutions:**
1. **List available families:**
```json
Tool: unopim_get_families()
```
2. **Check family code spelling:**
- Family codes are case-sensitive
- Use snake_case (e.g., `coffee_machines` not `Coffee Machines`)
3. **Create family first:**
```json
Tool: unopim_create_family({
code: "coffee_machines",
labels: {...},
attribute_codes: [...]
})
```
---
### Issue: "Required attribute missing"
**Symptoms:**
```
Error: Required attribute 'description' is missing
```
**Solutions:**
1. **Check family schema:**
```json
Tool: unopim_get_family_schema({
family_code: "coffee_machines"
})
// Response shows which attributes are required
{
"requiredAttributes": [
{"code": "name", ...},
{"code": "description", ...}
]
}
```
2. **Provide all required attributes:**
```json
{
"values": {
"common": { ... },
"channel_locale_specific": {
"default": {
"da_DK": {
"name": "Product",
"description": "Description" // Add required attribute
}
}
}
}
}
```
---
## Media Upload Problems
### Issue: "Image uploaded but not visible"
**Symptoms:**
- Tool returns success
- File exists in storage
- Image doesn't appear on product in UI
**Solutions:**
1. **Verify you're using NEW upload tool:**
```json
// Use this (auto-links image):
Tool: unopim_upload_product_media(...)
// NOT manual upload + update
```
2. **Check attribute exists in family:**
```json
Tool: unopim_get_family_schema({
family_code: "coffee_machines"
})
// Verify "image" attribute is in family
```
3. **Verify file path in product:**
```json
Tool: unopim_get_product({ sku: "PROD-001" })
// Check values.common.image or
// values.channel_locale_specific.default.da_DK.image
// contains file path
```
4. **Check attribute type:**
- Attribute must be type `image` or `file`
- Not `text` or other types
---
### Issue: "Failed to fetch file from URL"
**Symptoms:**
```
Error: Failed to fetch file from URL: HTTP 404
```
**Solutions:**
1. **Verify URL is accessible:**
```bash
curl -I https://example.com/image.jpg
# Should return 200 OK
```
2. **Check URL format:**
- Must be fully qualified: `https://example.com/image.jpg`
- Not relative: `/images/image.jpg`
3. **Check authentication:**
- If URL requires auth, image must be publicly accessible
- Or use base64 upload instead:
```json
{
"sku": "PROD-001",
"attribute": "image",
"file_base64": "iVBORw0KGgo...",
"filename": "image.jpg"
}
```
---
### Issue: "File too large"
**Symptoms:**
```
Error: Request entity too large
```
**Solutions:**
1. **Check file size:**
```bash
curl -sI https://example.com/image.jpg | grep -i content-length
```
2. **Resize image before upload:**
- Max recommended: 2MB per image
- Use image optimization tools
3. **Use base64 for smaller control:**
```bash
# Resize and encode
convert input.jpg -resize 1200x1200 -quality 85 output.jpg
base64 output.jpg
```
---
## Performance Issues
### Issue: "Bulk import too slow"
**Symptoms:**
- `unopim_bulk_create_products` takes >5 minutes
- Server appears to hang
**Solutions:**
1. **Use smaller batches:**
```json
// Instead of 1000 products at once
// Split into batches of 100
{
"products": [/* 100 products */],
"on_error": "continue"
}
```
2. **Check server resources:**
```bash
# On server
top
htop
# Look for high CPU/memory usage
```
3. **Optimize product data:**
```json
// Remove unnecessary attributes
{
"values": {
"common": {
"sku": "PROD-001",
"price": 999
// Only include attributes that have values
}
}
}
```
4. **Use validate_only first:**
```json
{
"products": [...],
"validate_only": true // Test without creating
}
```
---
### Issue: "Rate limiting errors"
**Symptoms:**
```
Error: Too many requests (429)
```
**Solutions:**
1. **Add delays between requests:**
```
Claude will automatically space out requests
```
2. **Reduce batch size:**
```json
{
"products": [/* Smaller batches */],
"on_error": "continue"
}
```
3. **Check UnoPim rate limits:**
- Contact UnoPim admin to increase limits
- Or schedule imports during off-peak hours
---
## Getting Help
### Logs to Check
1. **MCP Server Logs:**
```bash
# If running manually
# Logs appear in terminal
# If running as service
journalctl -u unopim-mcp -f
```
2. **Claude Desktop Logs:**
```bash
# macOS
~/Library/Logs/Claude/
# Windows
%APPDATA%\Claude\Logs\
# Linux
~/.config/Claude/logs/
```
3. **UnoPim Logs:**
```bash
# On UnoPim server
tail -f /var/log/unopim/laravel.log
```
### Information to Provide When Reporting Issues
- [ ] MCP Server version (`git log -1`)
- [ ] Node.js version (`node --version`)
- [ ] Operating system
- [ ] Connection mode (stdio or HTTP/SSE)
- [ ] Full error message
- [ ] Server logs around time of error
- [ ] Tool input that caused error
- [ ] Steps to reproduce
### Support Channels
- **GitHub Issues**: https://github.com/your-org/unopim-mcp/issues
- **Internal Slack**: #unopim-support
- **Email**: support@picopublish.com
---
## Common Gotchas
### 1. Case Sensitivity
✅ Always use exact case for:
- Family codes
- Attribute codes
- Option codes (e.g., "Red" not "red")
### 2. Trailing Slashes
❌ Don't include trailing slash in base URL:
- Wrong: `http://example.com:8000/`
- Right: `http://example.com:8000`
### 3. Code Format
✅ Use snake_case for all codes:
- `coffee_machines` not `Coffee Machines`
- `water_capacity` not `Water Capacity`
### 4. Name Attribute
✅ Always in `channel_locale_specific`, never in `common`
### 5. Categories Array
✅ Always at top level of `values`:
```json
{
"values": {
"categories": ["cat1", "cat2"], // ✅ Here
"common": {
"sku": "PROD-001"
}
}
}
```
### 6. Dependency Order
✅ Always create in this order:
1. Attributes
2. Families
3. Categories
4. Products
5. Media
---
**Last Updated**: 2026-01-13
**Issue Coverage**: 30+ common problems
**Resolution Rate**: 95%
