# Troubleshooting Publishing Issues in xiaohongshu-mcp: A Complete Guide

> Resolve xiaohongshu-mcp publishing issues by troubleshooting DOM blocking, tab switching, and upload timeouts. Learn essential debugging steps to fix failures in this comprehensive guide.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: how-to-guide
- Published: 2026-03-09

---

**The most common publishing failures in xiaohongshu-mcp stem from DOM blocking elements, navigation tab switching errors, and upload timeouts, which can be diagnosed by checking the `mustClickPublishTab`, `removePopCover`, and `waitForUploadComplete` functions in the source code.**

When automating content publication to 小红书 (Xiaohongshu) using the `xpzouying/xiaohongshu-mcp` repository, failures typically occur within the browser automation layer built on *go-rod*. Understanding the specific failure points in [`xiaohongshu/publish.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go) and [`xiaohongshu/publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish_video.go) allows you to implement effective troubleshooting publishing issues in xiaohongshu-mcp workflows.

## Common Publishing Failure Points

### Navigation and Tab Switching Errors

The publishing flow begins by navigating to the creator studio and switching to the appropriate upload tab. When `NewPublishImageAction` or `NewPublishVideoAction` initializes, it calls `mustClickPublishTab` ([publish.go L59-L62](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L59)).

If you encounter errors like **"未找到发布 TAB"** (publish tab not found) or **"切换到上传图文失败"** (failed to switch to image upload), verify that:
- The browser page has fully loaded the creator studio URL
- The DOM selectors for the publish tab haven't changed in the Xiaohongshu UI
- No network interception is blocking the creator studio JavaScript

### DOM Blocking and Element Visibility

Xiaohongshu's interface frequently displays pop-ups, notifications, or cookie banners that block interaction with underlying elements. The code attempts to handle this via `removePopCover` and `isElementBlocked` ([publish.go L35-L41](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L35)).

Symptoms include:
- **"发布 TAB 被遮挡"** (publish tab is blocked)
- Click events that return success but trigger no UI change
- Timeouts waiting for element visibility

To resolve these issues, manually inspect the page for `div.d-popover` elements or modal overlays. The automation expects a clean DOM state before proceeding with `mustClickPublishTab`.

### Image and Video Upload Timeouts

File upload operations are asynchronous and depend on Xiaohongshu's CDN processing. The image upload flow uses `uploadImages` which calls `waitForUploadComplete` ([publish.go L43-L71](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L43)), while video publishing uses `uploadVideo` ([publish_video.go L73-L90](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish_video.go#L73)).

Common upload failures include:
- **"图片上传超时"** (image upload timeout)
- **"未找到视频上传输入框"** (video upload input not found)
- Preview images that never appear in the UI

The code waits for the selector `.img-preview-area .pr` to match the expected image count. If Xiaohongshu updates their CSS classes, this selector will fail and require updating in `waitForUploadComplete`.

### Content Validation Errors

Before submission, the code validates title and content length constraints via `checkTitleMaxLength` and `checkContentMaxLength` ([publish.go L64-L84](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L64)).

Errors you may encounter:
- **"标题超过最大长度"** (title exceeds maximum length)
- **"正文超过最大长度"** (content exceeds maximum length)

These validations mirror the UI constraints found in `div.title-container div.max_suffix` and `div.edit-container div.length-error`. Ensure your content respects these limits before calling the publish action.

### Schedule and Visibility Configuration

Advanced publishing options include scheduling and visibility settings, handled by `setSchedulePublish` and `setVisibility` ([publish.go L47-L55](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L47)).

Troubleshooting tips:
- Use exact Chinese strings for visibility: `公开可见`, `仅自己可见`, or `仅互关好友可见`
- Schedule times must be in RFC3339 format and in the future
- If the scheduled post never appears, verify the system clock and timezone settings

### Product Binding and Original Declaration

E-commerce features and copyright declarations add complexity via `bindProducts` ([publish.go L45-L53](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L45)) and `setOriginal` with `confirmOriginalDeclaration` ([publish.go L98-L108](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L98)).

Common issues:
- **"绑定商品失败"** (product binding failed) when the "添加商品" button is not found
- **"原创声明弹窗卡死"** (original declaration popup freeze) when the confirmation checklist selector fails

Ensure the product search workflow in `searchAndSelectProduct` can locate your items, and verify that the original declaration popup DOM structure matches the selectors in `confirmOriginalDeclaration`.

## Step-by-Step Debugging Checklist

Follow this systematic approach to isolate publishing failures:

1. **Verify Login State** – Ensure the browser session is authenticated using `LoginAction.CheckLoginStatus`. If unauthenticated, fetch the QR code via `FetchQrcodeImage` and wait for login completion with `WaitForLogin`.

2. **Confirm Navigation** – Manually open `https://creator.xiaohongshu.com/publish/publish?source=official` and verify the "上传图文" or "上传视频" tab is present and clickable.

3. **Inspect DOM Blocking** – Check for floating pop-overs (`div.d-popover`) or modal overlays. The `removePopCover` function attempts to delete these automatically, but manual intervention may be required if selectors change.

4. **Validate File Paths** – Run `os.Stat` checks on image and video paths. Missing files cause early returns before upload begins.

5. **Monitor Upload Progress** – Watch console logs for "图片已提交上传" messages and preview counts in `waitForUploadComplete`. If the `.img-preview-area .pr` selector fails to match expected counts, update the selector in the source.

6. **Check Content Constraints** – Verify title and content lengths respect UI limits displayed in `div.max_suffix` and `div.length-error` elements to avoid `makeMaxLengthError` returns.

7. **Validate Schedule and Visibility** – Use exact Chinese visibility strings (`公开可见`, `仅自己可见`, `仅互关好友可见`) and RFC3339 formatted schedule times.

8. **Handle Popups and Declarations** – For original declarations, ensure the popup DOM structure matches `confirmOriginalDeclaration` selectors. For product binding, verify `clickAddProductButton` can locate the add product button.

9. **Analyze Error Traces** – When errors occur, inspect the wrapped stack trace produced by `github.com/pkg/errors` to identify the exact function and line number causing the failure.

## Code Examples for Error Handling

The following examples demonstrate robust error handling patterns when troubleshooting publishing issues in xiaohongshu-mcp.

### Retry Logic for Image Publishing

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/go-rod/rod"
	"xiao/hongshu/v2/xiaohongshu"
)

func main() {
	browser := rod.New().MustConnect()
	defer browser.Close()
	page := browser.MustPage()
	defer page.Close()

	// Ensure login first (omitted for brevity)
	//
	action, err := xiaohongshu.NewPublishImageAction(page)
	if err != nil {
		panic(fmt.Sprintf("create action failed: %v", err))
	}

	content := xiaohongshu.PublishImageContent{
		Title:      "我的第一篇笔记",
		Content:    "这是使用 xiaohongshu‑mcp 自动发布的内容",
		ImagePaths: []string{"/tmp/pic1.jpg", "/tmp/pic2.jpg"},
		Tags:       []string{"#自动化", "#go"},
		Visibility: "公开可见",
	}

	// Simple retry loop
	for i := 0; i < 3; i++ {
		if err := action.Publish(context.Background(), content); err != nil {
			fmt.Printf("publish attempt %d failed: %v\n", i+1, err)
			time.Sleep(2 * time.Second)
			continue
		}
		fmt.Println("publish succeeded")
		break
	}
}

```

### HTTP API Error Handling

```go
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"time"
)

type VideoReq struct {
	Title        string   `json:"title"`
	Content      string   `json:"content"`
	Video        string   `json:"video"` // absolute local path
	Tags         []string `json:"tags,omitempty"`
	Visibility   string   `json:"visibility,omitempty"`
	ScheduleTime string   `json:"schedule_time,omitempty"` // RFC3339, optional
	Products     []string `json:"products,omitempty"`
}

func main() {
	req := VideoReq{
		Title:      "演示视频",
		Content:    "使用 MCP 发布的演示视频",
		Video:      "/Users/me/Videos/demo.mp4",
		Tags:       []string{"#demo"},
		Visibility: "仅自己可见",
	}
	body, _ := json.Marshal(req)

	resp, err := http.Post("http://localhost:18060/api/v1/publish_video",
		"application/json", bytes.NewReader(body))
	if err != nil {
		panic("request failed: " + err.Error())
	}
	defer resp.Body.Close()

	var out map[string]interface{}
	_ = json.NewDecoder(resp.Body).Decode(&out)

	if resp.StatusCode != http.StatusOK {
		// API returns a unified error object
		fmt.Printf("publish error: %v\n", out["error"])
		return
	}
	fmt.Printf("publish success: %v\n", out["data"])
}

```

## Key Source Files for Troubleshooting

Understanding the codebase structure accelerates debugging. Focus on these files when troubleshooting publishing issues in xiaohongshu-mcp:

| File | Role |
|------|------|
| [`xiaohongshu/publish.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go) | Core image-note publishing flow – navigation, image upload, title/content handling, schedule, visibility, original flag, product binding, final submit. Contains `mustClickPublishTab`, `removePopCover`, `waitForUploadComplete`, and `checkTitleMaxLength`. |
| [`xiaohongshu/publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish_video.go) | Video-note publishing – video upload, waiting for processing, and reuse of common UI helpers. Implements `uploadVideo` and `waitForPublishButtonClickable`. |
| [`xiaohongshu/login.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/login.go) | Login management and QR-code handling; required before any publish action. Check `CheckLoginStatus` and `WaitForLogin` for authentication issues. |
| [`docs/API.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docs/API.md) | HTTP/MCP API specification – useful when troubleshooting via the external API rather than the Go SDK. |
| [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go) | Registers the HTTP endpoints that map to the publishing functions. |
| [`README.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/README.md) | Quick start guide, environment setup, and known limitations. |

## Summary

Troubleshooting publishing issues in xiaohongshu-mcp requires systematic verification of the browser automation pipeline built on go-rod. Key takeaways include:

- **Authentication first**: Always verify login status via `CheckLoginStatus` before attempting publishes, as unauthenticated sessions fail silently during navigation.
- **DOM cleanliness**: Remove blocking pop-overs using `removePopCover` or manual intervention when `isElementBlocked` detects interference with the publish tab.
- **Selector maintenance**: Update CSS selectors in `waitForUploadComplete` and `confirmOriginalDeclaration` when Xiaohongshu UI changes cause "element not found" errors.
- **Content constraints**: Respect title and content length limits enforced by `checkTitleMaxLength` and `checkContentMaxLength` to avoid validation errors.
- **Visibility strings**: Use exact Chinese strings (`公开可见`, `仅自己可见`, `仅互关好友可见`) for visibility settings to prevent configuration failures.

## Frequently Asked Questions

### Why does the publish button remain disabled when uploading video?

The video publishing flow in [`xiaohongshu/publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish_video.go) uses `waitForPublishButtonClickable` to poll the button's `disabled` attribute and class name. If the button stays disabled, the video is likely still processing on Xiaohongshu's servers. Increase the `maxWait` timeout in the configuration or check the browser console for upload errors. Ensure the video file path is absolute and accessible, as `uploadVideo` performs `os.Stat` validation before attempting upload.

### How do I fix "未找到发布 TAB" errors?

This error originates in `mustClickPublishTab` ([publish.go L59-L62](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L59)) when the selector for the publish tab returns no elements. First, manually navigate to `https://creator.xiaohongshu.com/publish/publish?source=official` and verify the tab exists. If Xiaohongshu has updated their UI, you must update the CSS selectors in the source code. Also check for pop-overs blocking the tab using `removePopCover` or `isElementBlocked` ([publish.go L35-L41](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L35)).

### What causes image upload timeouts and how can I resolve them?

Image upload timeouts occur in `waitForUploadComplete` ([publish.go L43-L71](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go#L43)) when the expected number of preview elements (matching `.img-preview-area .pr`) fails to appear within the timeout window. This usually indicates either slow network conditions to Xiaohongshu's CDN or a changed DOM structure. Verify that your image files exist at the specified paths before upload begins, as the code checks `os.Stat` early in the flow. If the CSS selector has changed, update the selector string in `waitForUploadComplete` and recompile.

### Where can I find detailed error logs when publishing fails?

The xiaohongshu-mcp library uses `github.com/pkg/errors` to wrap errors with stack traces throughout the publishing pipeline. When `action.Publish()` returns an error, inspect the error string for references to specific functions like `mustClickPublishTab`, `uploadImages`, or `submitPublish`. For HTTP API users, check the JSON response body for the `"error"` field. Additionally, enable structured logging in your Go application to capture `slog.Info` outputs from the library, which log key milestones like "图片已提交上传" (images submitted for upload) and upload completion counts.